
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />

    <title>FAQ &#8212; Leo 6.7.2 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
    <link rel="stylesheet" type="text/css" href="_static/custom.css" />
    
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    
    <script src="_static/sidebar.js"></script>
    
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Leo’s Cheat Sheet" href="cheatsheet.html" />
    <link rel="prev" title="More Leo Links" href="toc-more-links.html" /> 
  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="cheatsheet.html" title="Leo’s Cheat Sheet"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="toc-more-links.html" title="More Leo Links"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="leo_toc.html">Leo 6.7.2 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="toc-more-links.html" accesskey="U">More Leo Links</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">FAQ</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="faq">
<h1>FAQ<a class="headerlink" href="#faq" title="Permalink to this heading">¶</a></h1>
<p>This is Leo’s Frequently Asked Questions document.</p>
<div class="contents local topic" id="contents">
<span id="index-0"></span><p class="topic-title">Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#getting-leo" id="id4">Getting Leo</a></p>
<ul>
<li><p><a class="reference internal" href="#where-can-i-get-official-releases-of-leo" id="id5">Where can I get official releases of Leo?</a></p></li>
<li><p><a class="reference internal" href="#installing-leo-with-git" id="id6">Installing Leo with git</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-get-recent-snapshots-of-leo" id="id7">How can I get recent snapshots of Leo?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#installing-leo" id="id8">Installing Leo</a></p>
<ul>
<li><p><a class="reference internal" href="#how-to-pip-install-from-github" id="id9">How to  Pip install from GitHub?</a></p></li>
<li><p><a class="reference internal" href="#leo-s-installer-failed-what-do-i-do" id="id10">Leo’s installer failed, what do I do?</a></p></li>
<li><p><a class="reference internal" href="#common-problems" id="id11">Common problems</a></p></li>
<li><p><a class="reference internal" href="#tip-use-shallow-git-clones-to-speed-pip-install" id="id12">Tip: use shallow git clones to speed pip install</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#learning-to-use-leo" id="id13">Learning to use Leo</a></p>
<ul>
<li><p><a class="reference internal" href="#how-can-i-learn-leo-or-python-or-anything" id="id14">How can I learn Leo, or python, or anything</a></p></li>
<li><p><a class="reference internal" href="#what-s-the-best-way-to-learn-to-use-leo" id="id15">What’s the best way to learn to use Leo?</a></p></li>
<li><p><a class="reference internal" href="#when-is-using-a-section-better-than-using-a-method" id="id16">When is using a section better than using a method?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#abbreviations" id="id17">Abbreviations</a></p>
<ul>
<li><p><a class="reference internal" href="#what-are-some-useful-abbreviations" id="id18">What are some useful abbreviations?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#id1" id="id19">Clones</a></p>
<ul>
<li><p><a class="reference internal" href="#how-can-i-customize-the-clone-find-all-commands" id="id20">How can I customize the clone-find-all commands?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-eliminate-clone-wars" id="id21">How can I eliminate clone wars?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-use-clones-to-reorganize-an-outline" id="id22">How can I use clones to reorganize an outline?</a></p></li>
<li><p><a class="reference internal" href="#how-does-ekr-use-clones" id="id23">How does EKR use clones?</a></p></li>
<li><p><a class="reference internal" href="#how-does-leo-handle-clone-conflicts" id="id24">How does Leo handle clone conflicts?</a></p></li>
<li><p><a class="reference internal" href="#when-is-deleting-a-node-dangerous" id="id25">When is deleting a node dangerous?</a></p></li>
<li><p><a class="reference internal" href="#when-may-i-delete-clones-safely" id="id26">When may I delete clones safely?</a></p></li>
<li><p><a class="reference internal" href="#why-doesn-t-leo-support-cross-outline-clones" id="id27">Why doesn’t Leo support cross-outline clones?</a></p></li>
<li><p><a class="reference internal" href="#why-is-alt-n-goto-next-clone-important" id="id28">Why is Alt-N (goto-next-clone) important?</a></p></li>
<li><p><a class="reference internal" href="#why-should-i-use-clones" id="id29">Why should I use clones?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#customizing-leo" id="id30">Customizing Leo</a></p>
<ul>
<li><p><a class="reference internal" href="#how-can-i-create-a-pane-for-matplotlib-charts" id="id31">How can I create a pane for matplotlib charts?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-customize-settings-for-a-particular-external-file" id="id32">How can I customize settings for a particular external file?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-enable-and-disable-support-for-psyco" id="id33">How can I enable and disable support for psyco?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-modify-an-existing-theme" id="id34">How can I modify an existing theme?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-put-background-images-in-the-body-pane" id="id35">How can I put background images in the body pane?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-run-code-at-startup" id="id36">How can I run code at startup?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-sync-settings-across-leo-files" id="id37">How can I sync settings across .leo files?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-enable-a-theme-leo-file" id="id38">How do I enable a theme .leo file?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-use-leo-s-legacy-key-bindings" id="id39">How can I use Leo’s legacy key bindings?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-add-a-new-menu-item-from-a-plugin" id="id40">How do I add a new menu item from a plugin?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-set-selection-colors" id="id41">How do I set selection colors?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-specify-qt-fonts" id="id42">How do I specify qt fonts?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-submit-a-plugin" id="id43">How do I submit a plugin?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#excel" id="id44">Excel</a></p>
<ul>
<li><p><a class="reference internal" href="#how-can-i-show-leo-files-with-excel" id="id45">How can I show Leo files with Excel?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#files" id="id46">Files</a></p>
<ul>
<li><p><a class="reference internal" href="#can-file-trees-contain-material-not-in-the-external-file" id="id47">Can &#64;file trees contain material not in the external file?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-avoid-getting-long-lines-in-external-files" id="id48">How can I avoid getting long lines in external files?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-create-a-template-leo-file" id="id49">How can I create a template .leo file?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-create-javascript-comments" id="id50">How can I create Javascript comments?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-disable-php-comments" id="id51">How can I disable PHP comments?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-open-special-leo-files-easily" id="id52">How can I open special .leo files easily?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-specify-the-root-directory-of-a-thumb-drive" id="id53">How can I specify the root directory of a thumb drive?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-use-leo-with-older-c-compilers" id="id54">How can I use Leo with older C compilers</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-use-leo-with-unsupported-languages" id="id55">How can I use Leo with unsupported languages?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-inhibit-sentinels-in-external-files" id="id56">How do I inhibit sentinels in external files?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-make-external-files-start-with-a-shebang-line" id="id57">How do I make external files start with a shebang line?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-prevent-leo-from-expanding-sections" id="id58">How do I prevent Leo from expanding sections?</a></p></li>
<li><p><a class="reference internal" href="#why-can-t-i-use-ignore-directives-in-file-trees" id="id59">Why can’t I use &#64;ignore directives in &#64;file trees?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#id2" id="id60">Git</a></p>
<ul>
<li><p><a class="reference internal" href="#how-can-i-use-git-to-check-leo-s-importers" id="id61">How can I use git to check Leo’s importers?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-use-leo-with-git" id="id62">How can I use Leo with git?</a></p></li>
<li><p><a class="reference internal" href="#how-should-i-use-leo-with-git-etc" id="id63">How should I use Leo with git, etc.?</a></p></li>
<li><p><a class="reference internal" href="#what-is-a-reference-leo-file" id="id64">What is a reference .leo file?</a></p></li>
<li><p><a class="reference internal" href="#why-do-files-sometimes-change-when-switching-branches" id="id65">Why do files sometimes change when switching branches?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#graphics" id="id66">Graphics</a></p>
<ul>
<li><p><a class="reference internal" href="#how-can-i-display-graphics-in-leo" id="id67">How can I display graphics in Leo?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-make-a-screencast" id="id68">How can I make a screencast?</a></p>
<ul>
<li><p><a class="reference internal" href="#use-a-script-to-open-your-app" id="id69">Use a script to open your app</a></p></li>
<li><p><a class="reference internal" href="#debug-your-workflow-with-short-videos" id="id70">Debug your workflow with short videos</a></p></li>
<li><p><a class="reference internal" href="#emulate-the-screencast-com-tutorials" id="id71">Emulate the screencast.com tutorials</a></p></li>
<li><p><a class="reference internal" href="#record-your-first-real-take" id="id72">Record your first real take</a></p></li>
<li><p><a class="reference internal" href="#edit-your-raw-take" id="id73">Edit your raw take</a></p></li>
<li><p><a class="reference internal" href="#summary" id="id74">Summary</a></p></li>
<li><p><a class="reference internal" href="#additional-tips" id="id75">Additional tips</a></p></li>
<li><p><a class="reference internal" href="#tips-for-improving-audio" id="id76">Tips for improving audio</a></p></li>
</ul>
</li>
</ul>
</li>
<li><p><a class="reference internal" href="#importing-files" id="id77">Importing files</a></p>
<ul>
<li><p><a class="reference internal" href="#how-can-i-import-many-files-at-once" id="id78">How can I import many files at once?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#latex" id="id79">LaTeX</a></p>
<ul>
<li><p><a class="reference internal" href="#how-can-i-produce-pdf-output-from-latex-input" id="id80">How can I produce PDF output from LaTex input?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-use-bibtex-citations-from-leo" id="id81">How can I use BibTeX citations from Leo?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#markdown-sphinx" id="id82">Markdown &amp; Sphinx</a></p>
<ul>
<li><p><a class="reference internal" href="#how-can-i-create-markdown-files" id="id83">How can I create markdown files?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-create-a-markdown-table-of-contents" id="id84">How can I create a markdown table of contents?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-use-markdown-with-sphinx" id="id85">How can I use Markdown with Sphinx?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#scripting-testing" id="id86">Scripting &amp; Testing</a></p>
<ul>
<li><p><a class="reference internal" href="#how-can-i-create-buttons-with-dropdown-menus" id="id87">How can I create buttons with dropdown menus?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-make-commonly-used-scripts-widely-accessible" id="id88">How can I make commonly-used scripts widely accessible?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-organize-large-docstrings" id="id89">How can I organize large docstrings?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-run-code-in-an-external-process" id="id90">How can I run code in an external process?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-run-scripts-in-languages-other-than-python" id="id91">How can I run scripts in languages other than python?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-run-pylint-outside-of-leo" id="id92">How can I run pylint outside of Leo?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-test-settings-easily" id="id93">How can I test settings easily?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-use-leo-in-virtualenv" id="id94">How can I use Leo in virtualenv?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-use-setuptools-instead-of-bat-files" id="id95">How can I use setuptools instead of .bat files?</a></p></li>
<li><p><a class="reference internal" href="#how-can-scripts-call-functions-from-leo-s-core" id="id96">How can scripts call functions from Leo’s core?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-choose-between-others-and-section-references" id="id97">How do I choose between &#64;others and section references?</a></p></li>
<li><p><a class="reference internal" href="#how-to-use-leo-to-make-mathematical-notes" id="id98">How to use leo to make mathematical notes?</a></p></li>
<li><p><a class="reference internal" href="#what-is-an-easy-way-to-profile-code" id="id99">What is an easy way to profile code?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#trouble-shooting" id="id100">Trouble shooting</a></p>
<ul>
<li><p><a class="reference internal" href="#error-messages-from-the-rst3-plugin-aren-t-helpful-what-can-i-do" id="id101">Error messages from the rst3 plugin aren’t helpful. What can I do?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-move-leo-s-window-back-on-screen" id="id102">How can I move Leo’s window back on screen?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-run-leo-from-a-console-window" id="id103">How can I run Leo from a console window?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-use-python-s-pdb-debugger-with-leo" id="id104">How can I use Python’s pdb debugger with Leo?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-get-help" id="id105">How do I get help?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-make-ctrl-shift-0-work-on-windows-8-or-10" id="id106">How do I make Ctrl-Shift-0 work on Windows 8 or 10?</a></p></li>
<li><p><a class="reference internal" href="#how-do-i-report-bugs" id="id107">How do I report bugs?</a></p></li>
<li><p><a class="reference internal" href="#i-am-having-trouble-installing-leo-on-macos-what-should-i-do" id="id108">I am having trouble installing Leo on MacOS. What should I do?</a></p></li>
<li><p><a class="reference internal" href="#i-can-t-run-the-leobridge-module-outside-of-leo-core-what-should-i-do" id="id109">I can’t run the LeoBridge module outside of leo/core.  What should I do?</a></p></li>
<li><p><a class="reference internal" href="#i-can-t-write-imported-files-what-s-going-on" id="id110">I can’t write Imported files.  What’s going on?</a></p></li>
<li><p><a class="reference internal" href="#my-old-leo-files-won-t-load-using-leo-4-5-or-later-what-should-i-do" id="id111">My old .leo files won’t load using Leo 4.5 or later. What should I do?</a></p></li>
<li><p><a class="reference internal" href="#nothing-or-almost-nothing-happens-when-i-start-leo-what-should-i-do" id="id112">Nothing (or almost nothing) happens when I start Leo.  What should I do?</a></p></li>
<li><p><a class="reference internal" href="#running-python-setup-py-install-from-the-leo-directory-doesn-t-work-why-not" id="id113">Running Python setup.py install from the leo directory doesn’t work.  Why not?</a></p></li>
<li><p><a class="reference internal" href="#the-new-python-decorator-syntax-causes-problems-what-can-i-do" id="id114">The new Python decorator syntax causes problems.  What can I do?</a></p></li>
<li><p><a class="reference internal" href="#themes-aren-t-working-for-me-what-should-i-do" id="id115">Themes aren’t working for me. What should I do?</a></p></li>
<li><p><a class="reference internal" href="#why-didn-t-leo-update-my-clean-outline-as-expected" id="id116">Why didn’t Leo update my &#64;clean outline as expected?</a></p></li>
<li><p><a class="reference internal" href="#why-do-qt-windows-disappear-in-my-scripts" id="id117">Why do Qt windows disappear in my scripts?</a></p></li>
<li><p><a class="reference internal" href="#why-isn-t-the-spell-tab-showing" id="id118">Why isn’t the Spell tab showing?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#id3" id="id119">Unicode</a></p>
<ul>
<li><p><a class="reference internal" href="#i-can-not-enter-non-ascii-characters-what-can-i-do" id="id120">I can not enter non-ascii characters.  What can I do?</a></p></li>
<li><p><a class="reference internal" href="#some-characters-in-external-files-look-funny-what-can-i-do" id="id121">Some characters in external files look funny. What can I do?</a></p></li>
<li><p><a class="reference internal" href="#i-get-weird-results-when-defining-unicode-strings-in-scripts-what-is-going-on" id="id122">I get weird results when defining unicode strings in scripts.  What is going on?</a></p></li>
<li><p><a class="reference internal" href="#some-characters-are-garbled-when-importing-files-what-can-i-do" id="id123">Some characters are garbled when importing files. What can I do?</a></p></li>
<li><p><a class="reference internal" href="#python-s-print-statement-shows-byte-hash-for-unicode-characters-what-can-i-do" id="id124">Python’s print statement shows ‘byte hash’ for unicode characters.  What can I do?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#vim" id="id125">Vim</a></p>
<ul>
<li><p><a class="reference internal" href="#how-can-i-use-leo-s-bridge-in-vim" id="id126">How can I use Leo’s bridge in vim?</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#work-flow" id="id127">Work flow</a></p>
<ul>
<li><p><a class="reference internal" href="#how-can-i-organize-data-so-i-can-find-stuff-later" id="id128">How can I organize data so I can find stuff later?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-restore-focus-without-using-the-mouse" id="id129">How can I restore focus without using the mouse</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-see-two-nodes-at-once" id="id130">How can I see two nodes at once?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-use-leo-cooperatively-without-sentinels" id="id131">How can I use Leo cooperatively without sentinels?</a></p></li>
<li><p><a class="reference internal" href="#how-can-i-use-the-gtd-workflow-in-leo" id="id132">How can I use the GTD workflow in Leo?</a></p></li>
<li><p><a class="reference internal" href="#what-s-the-recommended-way-to-upgrade-leo" id="id133">What’s the recommended way to upgrade Leo?</a></p></li>
</ul>
</li>
</ul>
</div>
<section id="getting-leo">
<h2><a class="toc-backref" href="#id4">Getting Leo</a><a class="headerlink" href="#getting-leo" title="Permalink to this heading">¶</a></h2>
<section id="where-can-i-get-official-releases-of-leo">
<h3><a class="toc-backref" href="#id5">Where can I get official releases of Leo?</a><a class="headerlink" href="#where-can-i-get-official-releases-of-leo" title="Permalink to this heading">¶</a></h3>
<p>See <a class="reference external" href="download.html">Leo’s download page</a>.</p>
</section>
<section id="installing-leo-with-git">
<h3><a class="toc-backref" href="#id6">Installing Leo with git</a><a class="headerlink" href="#installing-leo-with-git" title="Permalink to this heading">¶</a></h3>
<p><strong>Important</strong>: This section tells how to set up <a class="reference external" href="https://git-scm.com/">git</a> so that you can grab
the latest sources using <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span></code>.</p>
<p>Many users will want to track the development version of Leo, in order to stay
on top of the latest features and bug fixes. Running the development version is
quite safe and easy, and it’s also a requirement if you want to contribute to
Leo.</p>
<ol class="arabic">
<li><p>First, you need to get git from <a class="reference external" href="http://git-scm.com/">http://git-scm.com/</a>.</p></li>
<li><p>Get Leo from GitHub by doing:</p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">--depth=500</span> <span class="pre">--no-single-branch</span> <span class="pre">https://github.com/leo-editor/leo-editor</span></code> (http access)</p>
<p>or:</p>
<p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">--depth=500</span>&#160; <span class="pre">--no-single-branch</span> <span class="pre">git&#64;github.com:leo-editor/leo-editor.git</span></code> (ssh access)</p>
<p>followed by checking out the _devel_ branch:</p>
</div></blockquote>
</li>
</ol>
<p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">devel</span></code></p>
<ol class="arabic" start="3">
<li><p>Install dependencies and create leo script launcher:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">editable</span> <span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">leo</span><span class="o">-</span><span class="n">editor</span>
</pre></div>
</div>
</li>
</ol>
<p>And that’s it! You can run leo with <cite>PYTHONHOME/Scripts/leo</cite> or <cite>python leo-editor/launchLeo.py</cite>. When you want to refresh the code with latest modifications from GitHub, run <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code>.</p>
</section>
<section id="how-can-i-get-recent-snapshots-of-leo">
<h3><a class="toc-backref" href="#id7">How can I get recent snapshots of Leo?</a><a class="headerlink" href="#how-can-i-get-recent-snapshots-of-leo" title="Permalink to this heading">¶</a></h3>
<p>Daily snapshots are available <a class="reference external" href="download.html">here</a>.</p>
</section>
</section>
<section id="installing-leo">
<h2><a class="toc-backref" href="#id8">Installing Leo</a><a class="headerlink" href="#installing-leo" title="Permalink to this heading">¶</a></h2>
<section id="how-to-pip-install-from-github">
<h3><a class="toc-backref" href="#id9">How to  Pip install from GitHub?</a><a class="headerlink" href="#how-to-pip-install-from-github" title="Permalink to this heading">¶</a></h3>
<p><strong>Problem</strong></p>
<p>When installing Leo from GitHub with
<code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">https://github.com/leo-editor/leo-editor/archive/devel.zip</span></code>
numerous files are left out.</p>
<p><strong>Solution</strong></p>
<p>Installing from Github into a new environment must be done in discrete
steps: download, unpack, and install in editable mode.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">wget</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">leo</span><span class="o">-</span><span class="n">editor</span><span class="o">/</span><span class="n">leo</span><span class="o">-</span><span class="n">editor</span><span class="o">/</span><span class="n">archive</span><span class="o">/</span><span class="n">devel</span><span class="o">.</span><span class="n">zip</span>
<span class="mi">7</span><span class="n">z</span> <span class="n">x</span> <span class="n">devel</span><span class="o">.</span><span class="n">zip</span> <span class="o">-</span><span class="n">o</span> <span class="n">C</span><span class="p">:</span>\<span class="n">apps</span>
<span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">editable</span> <span class="n">C</span><span class="p">:</span>\<span class="n">apps</span>\<span class="n">leo</span><span class="o">-</span><span class="n">editor</span><span class="o">-</span><span class="n">devel</span>
</pre></div>
</div>
<p>On Windows there are powershell versions of wget if needed.</p>
<p>For easier upgrading substitute <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span></code> for <code class="docutils literal notranslate"><span class="pre">wget</span></code> &amp; <code class="docutils literal notranslate"><span class="pre">7z</span></code>
steps:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="o">--</span><span class="n">single</span><span class="o">-</span><span class="n">branch</span> <span class="o">-</span><span class="n">b</span> <span class="n">devel</span> <span class="o">--</span><span class="n">depth</span><span class="o">=</span><span class="mi">100</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">leo</span><span class="o">-</span><span class="n">editor</span><span class="o">/</span><span class="n">leo</span><span class="o">-</span><span class="n">editor</span><span class="o">.</span><span class="n">git</span>
<span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">editable</span> <span class="n">leo</span><span class="o">-</span><span class="n">editor</span>
</pre></div>
</div>
<p>Time passes, upgrade desired:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pushd</span> <span class="n">c</span><span class="p">:</span>\<span class="n">apps</span>\<span class="n">leo</span><span class="o">-</span><span class="n">editor</span>
<span class="n">git</span> <span class="n">pull</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">single-branch</span></code>, <code class="docutils literal notranslate"><span class="pre">b</span></code> and <code class="docutils literal notranslate"><span class="pre">depth</span></code> are all optional, but will
dramatically speed up download time as it only grabs the latest
development branch and skips all but the last couple weeks or months of
history.</p>
</section>
<section id="leo-s-installer-failed-what-do-i-do">
<h3><a class="toc-backref" href="#id10">Leo’s installer failed, what do I do?</a><a class="headerlink" href="#leo-s-installer-failed-what-do-i-do" title="Permalink to this heading">¶</a></h3>
<p>You can simply unpack Leo anywhere and run from there.  You don’t need the installer.</p>
<p>From a console window, cd to the top-level leo folder.  Run Leo as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">launchLeo</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>To run Leo with Qt look and feel, use the –gui=qt option:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">launchLeo</span><span class="o">.</span><span class="n">py</span> <span class="o">--</span><span class="n">gui</span><span class="o">=</span><span class="n">qt</span>
</pre></div>
</div>
<p>To load Leo’s source, load leoPyRef.leo:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">launchLeo</span><span class="o">.</span><span class="n">py</span> <span class="o">--</span><span class="n">gui</span><span class="o">=</span><span class="n">qt</span> <span class="n">leo</span>\\<span class="n">core</span>\\<span class="n">leoPyRef</span><span class="o">.</span><span class="n">leo</span>
</pre></div>
</div>
</section>
<section id="common-problems">
<h3><a class="toc-backref" href="#id11">Common problems</a><a class="headerlink" href="#common-problems" title="Permalink to this heading">¶</a></h3>
<p>Missing modules can cause installation problems. If the installer doesn’t work (or puts up a dialog containing no text), you may install Leo from the .zip file as described at <a class="reference external" href="installing.html#installing-leo-on-windows">How to install Leo on Windows</a>. However you are installing Leo, be sure to <a class="reference external" href="running.html#running-leo-from-a-console-window">run Leo in a console</a>. because as a last resort Leo prints error messages to the console.</p>
</section>
<section id="tip-use-shallow-git-clones-to-speed-pip-install">
<h3><a class="toc-backref" href="#id12">Tip: use shallow git clones to speed pip install</a><a class="headerlink" href="#tip-use-shallow-git-clones-to-speed-pip-install" title="Permalink to this heading">¶</a></h3>
<p>Tip: faster dev pip installs with shallow clones</p>
<p>When running <cite>pip install –editable path/to/leo</cite> the  “Installing build dependencies …” step can take a loooong time. Apparently this is because it creates a copy of the folder tree including the <cite>.git</cite> folder, which can be quite large (ref). My machine right now: .git is 183 MB, while Leo is only 40 MB.</p>
<p>Solution: periodically create a new leo-editor shallow clone:</p>
<p>cd d:code
git clone –depth=100 https://github.com/leo-editor/leo-editor.git d:/code/shallow-leo-editor
move d:codeleo-editor d:codeleo-editor-bloated
move d:codeshallow-leo-editor d:codeleo-editor</p>
<p>At current commit rate:</p>
<blockquote>
<div><p>depth=100 is 6 months of history and 60mb (.git &amp; Leo together)
depth=500 is 2 years and 73 MB
depth={infinity} is 11 years and 242 MB</p>
</div></blockquote>
<p>The command shown only fetches master branch, and checkout of other branches will fail. Two solutions:</p>
<p># add all remote branch names
# use ‘devel’ instead of ‘*’ to get only devel branch
# quotes are significant
git remote set-branches origin ‘*’
git fetch
git checkout devel</p>
<p>Or:</p>
<p># shallow clone each branch
git clone –depth=nn –no-single-branch …</p>
</section>
</section>
<section id="learning-to-use-leo">
<h2><a class="toc-backref" href="#id13">Learning to use Leo</a><a class="headerlink" href="#learning-to-use-leo" title="Permalink to this heading">¶</a></h2>
<section id="how-can-i-learn-leo-or-python-or-anything">
<h3><a class="toc-backref" href="#id14">How can I learn Leo, or python, or anything</a><a class="headerlink" href="#how-can-i-learn-leo-or-python-or-anything" title="Permalink to this heading">¶</a></h3>
<p>Let us think of lessons not as explanations, but as puzzles to be solved by the student. The puzzles themselves need no lengthy explanations. They can even be cryptic. This attitude arises from two principles:</p>
<ol class="arabic simple">
<li><p>The less said, the better.</p></li>
<li><p>Invite people to learn for themselves.</p></li>
</ol>
<p><strong>Pick something that interests you</strong></p>
<p>Pick a real, worthy, programming task that you (the student) personally want/need to do in Leo. <em>This step is essential</em>! It is <em>useless</em> to try to learn in a vacuum.</p>
<p>EKR’s first python program was C2Py. leoAttic.txt contains the original version. Leo’s c-to-python commands contained revised code.</p>
<p><strong>Overcome fear of crashes and mistakes</strong></p>
<ul class="simple">
<li><p>Run Leo from a console.</p></li>
<li><p>Single-step through your code with g.pdb()</p></li>
<li><p>Deliberately put a crasher in your code and see what happens.</p></li>
</ul>
<p>The only way to hard crash Leo is to pass bad pointers to PyQt. Python should catch all other problems. If it doesn’t, report a bug to the python people ;-)</p>
<p><strong>Discover how Leo’s code works</strong></p>
<ul class="simple">
<li><p>Where is Leo’s source code? Hint: look for leoPy.leo in LeoDocs.leo.</p></li>
<li><p>Look at Leo’s demote command.
- What are three ways of finding the demote command?
- How does demote change the outline?
- How does demote handle undo?</p></li>
<li><p>Study any other Leo command that relates to your project.</p></li>
<li><p>Use the cff command to find all definitions of x.</p></li>
<li><p>Use the cff command to find all uses of x.</p></li>
</ul>
<p><strong>Start using Leo for real</strong></p>
<ul class="simple">
<li><p>Add a new command using &#64;button.</p></li>
<li><p>Create an external file containing your real-world project.
Execute it outside of Leo.</p></li>
<li><p>Write a Leo plugin.</p></li>
<li><p>Advanced: fix one of Leo’s bugs.</p></li>
</ul>
<p><strong>Attitude</strong></p>
<p>Students should always feel free to ask for help, but struggle teaches us the most. <strong>It doesn’t matter how long it takes to learn something</strong>. In our culture, we value quickness. But that is a trap. All learning builds momentum:</p>
<ul class="simple">
<li><p>Put 10 units of effort in, get 1 unit of results out.</p></li>
<li><p>Put 1 in, get 1 out.</p></li>
<li><p>Put 1 in, get 10 out.</p></li>
</ul>
<p>There is no other way! How many times have we given up just because things were not easy or clear at first?</p>
<p><strong>That which we learn, we learn by doing</strong></p>
<p>Reading about (and thinking about) are useful, but not good enough. That is why students must have a project that is important to them.  The project will put them into action.</p>
</section>
<section id="what-s-the-best-way-to-learn-to-use-leo">
<h3><a class="toc-backref" href="#id15">What’s the best way to learn to use Leo?</a><a class="headerlink" href="#what-s-the-best-way-to-learn-to-use-leo" title="Permalink to this heading">¶</a></h3>
<p>First, read <a class="reference external" href="tutorial.html">Leo’s tutorials</a>. This will be enough to get you started if you just want to use Leo as an <a class="reference external" href="glossary.html#outliner">outliner</a>. If you intend to use Leo for programming, read the <a class="reference external" href="tutorial-scripting.html">scripting tutorial</a>, then look at Leo’s source code in the file LeoPy.leo. Spend 5 or 10 minutes browsing through the outline. Don’t worry about details; just look for the following common usage patterns:</p>
<ul class="simple">
<li><p>The (Projects) tree shows how to use clones to represent tasks.</p></li>
<li><p>Study &#64;file leoNodes.py. It shows how to define more than one class in single file.</p></li>
<li><p>Most other files show how to use a single &#64;others directive to define one class.</p></li>
<li><p>Most methods are defined using &#64;others, <em>not</em> section definition nodes.</p></li>
</ul>
</section>
<section id="when-is-using-a-section-better-than-using-a-method">
<h3><a class="toc-backref" href="#id16">When is using a section better than using a method?</a><a class="headerlink" href="#when-is-using-a-section-better-than-using-a-method" title="Permalink to this heading">¶</a></h3>
<p>Use methods for any code that is used (called or referenced) more than once.</p>
<p><a class="reference external" href="glossary.html#sections">Sections</a> are convenient in the following circumstances:</p>
<ul>
<li><p>When you want to refer to snippets of code the can not be turned into methods. For example, many plugins start with the code like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&lt;&lt;</span> <span class="n">docstring</span> <span class="o">&gt;&gt;</span>
<span class="o">&lt;&lt;</span> <span class="n">imports</span> <span class="o">&gt;&gt;</span>
<span class="o">&lt;&lt;</span> <span class="n">version</span> <span class="n">history</span> <span class="o">&gt;&gt;</span>
<span class="o">&lt;&lt;</span> <span class="nb">globals</span> <span class="o">&gt;&gt;</span>

<span class="kc">None</span> <span class="n">of</span> <span class="n">these</span> <span class="n">sections</span> <span class="n">could</span> <span class="n">be</span> <span class="n">replaced</span> <span class="n">by</span> <span class="n">methods</span><span class="o">.</span>
</pre></div>
</div>
</li>
<li><p>When you want to refer to a snippet of code that shares local variables with the enclosing code. This is surprisingly easy and safe to do, <em>provided</em> the section is used only in one place. <a class="reference external" href="glossary.html#section-names">Section names</a> in such contexts can be clearer than method names.  For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&lt;&lt;</span> <span class="n">init</span> <span class="n">ivars</span> <span class="k">for</span> <span class="n">writing</span> <span class="o">&gt;&gt;</span>
</pre></div>
</div>
</li>
</ul>
<p>In short, I create sections when convenient, and convert them to functions or methods if they need to be used in several places.</p>
</section>
</section>
<section id="abbreviations">
<h2><a class="toc-backref" href="#id17">Abbreviations</a><a class="headerlink" href="#abbreviations" title="Permalink to this heading">¶</a></h2>
<section id="what-are-some-useful-abbreviations">
<h3><a class="toc-backref" href="#id18">What are some useful abbreviations?</a><a class="headerlink" href="#what-are-some-useful-abbreviations" title="Permalink to this heading">¶</a></h3>
<p>Edward Ream:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">alp</span><span class="p">;;</span><span class="o">=</span><span class="nd">@language</span> <span class="n">python</span>\<span class="n">n</span>
<span class="n">alr</span><span class="p">;;</span><span class="o">=</span><span class="nd">@language</span> <span class="n">rest</span>\<span class="n">n</span><span class="nd">@wrap</span>\<span class="n">n</span>
<span class="n">date</span><span class="p">;;</span><span class="o">=</span><span class="p">{</span><span class="o">|</span><span class="p">{</span><span class="kn">import</span> <span class="nn">time</span><span class="p">;</span><span class="n">x</span><span class="o">=</span><span class="n">time</span><span class="o">.</span><span class="n">asctime</span><span class="p">()}</span><span class="o">|</span><span class="p">}</span>
<span class="n">trace</span><span class="p">;;</span><span class="o">=</span><span class="n">trace</span> <span class="o">=</span> <span class="o">&lt;|</span><span class="nb">bool</span><span class="o">|&gt;</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">g</span><span class="o">.</span><span class="n">unitTesting</span>
</pre></div>
</div>
<p>John Lunzer:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">hl</span><span class="p">;;</span><span class="o">=</span><span class="p">{</span><span class="o">|</span><span class="p">{</span><span class="n">x</span><span class="o">=</span><span class="n">c</span><span class="o">.</span><span class="n">p</span><span class="o">.</span><span class="n">h</span><span class="p">}</span><span class="o">|</span><span class="p">}</span>
<span class="n">es</span><span class="p">;;</span><span class="o">=</span><span class="n">g</span><span class="o">.</span><span class="n">es</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span><span class="n">color</span><span class="o">=</span><span class="s1">&#39;&lt;|color|&gt;&#39;</span><span class="p">)</span>
<span class="n">ts</span><span class="p">;;</span><span class="o">=</span><span class="p">{</span><span class="o">|</span><span class="p">{</span><span class="n">x</span><span class="o">=</span><span class="n">time</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s2">&quot;%Y%m</span><span class="si">%d</span><span class="s2">%H%M%S&quot;</span><span class="p">)}</span><span class="o">|</span><span class="p">}</span>
</pre></div>
</div>
<p>Rob (Largo84):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ol</span><span class="p">;;</span><span class="o">=&lt;</span><span class="n">ol</span><span class="o">&gt;</span>\<span class="n">n</span>    <span class="o">&lt;</span><span class="n">li</span><span class="o">&gt;&lt;|</span><span class="n">item</span><span class="o">|&gt;&lt;/</span><span class="n">li</span><span class="o">&gt;</span>\<span class="n">n</span><span class="o">&lt;/</span><span class="n">ol</span><span class="o">&gt;</span>
<span class="n">li</span><span class="p">;;</span><span class="o">=&lt;</span><span class="n">li</span><span class="o">&gt;&lt;|</span><span class="n">ITEM</span><span class="o">|&gt;&lt;/</span><span class="n">li</span><span class="o">&gt;</span>
<span class="n">link</span><span class="p">;;</span><span class="o">=&lt;</span><span class="n">a</span> <span class="n">href</span><span class="o">=</span><span class="s2">&quot;&lt;|URL|&gt;&quot;</span> <span class="n">target</span><span class="o">=</span><span class="s2">&quot;_blank&quot;</span><span class="o">&gt;&lt;|</span><span class="n">TEXT</span><span class="o">|&gt;&lt;/</span><span class="n">a</span><span class="o">&gt;</span>
<span class="n">enum</span><span class="p">;;</span><span class="o">=</span>\<span class="n">begin</span><span class="p">{</span><span class="nb">enumerate</span><span class="p">}</span>\<span class="n">n</span>    \<span class="n">item</span> <span class="o">&lt;|</span><span class="n">item</span><span class="o">|&gt;</span>\<span class="n">n</span>\<span class="n">end</span><span class="p">{</span><span class="nb">enumerate</span><span class="p">}</span>
</pre></div>
</div>
<p>For more examples, see LeoSettings.leo.</p>
</section>
</section>
<section id="id1">
<h2><a class="toc-backref" href="#id19">Clones</a><a class="headerlink" href="#id1" title="Permalink to this heading">¶</a></h2>
<section id="how-can-i-customize-the-clone-find-all-commands">
<h3><a class="toc-backref" href="#id20">How can I customize the clone-find-all commands?</a><a class="headerlink" href="#how-can-i-customize-the-clone-find-all-commands" title="Permalink to this heading">¶</a></h3>
<p>The c.cloneFindAllAtNode and c.cloneFindAllFlattenedAtNode methods start the clone-find-all and clone-find-all-flattened commands at a particular node. For example, here is the body of <code class="docutils literal notranslate"><span class="pre">&#64;button</span> <span class="pre">cfa-code</span> <span class="pre">&#64;args</span> <span class="pre">add</span></code> in leoPy.leo:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">c</span><span class="o">.</span><span class="n">cloneFindAllFlattenedAtNode</span><span class="p">(</span><span class="s1">&#39;Code&#39;</span><span class="p">,</span><span class="n">top_level</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">&#64;args</span> <span class="pre">add</span></code> part of the headline causes Leo to add the <code class="docutils literal notranslate"><span class="pre">cfa-code</span></code> command to Leo’s history list, so there is no urgent need to use a separate key binding for this command.</p>
</section>
<section id="how-can-i-eliminate-clone-wars">
<h3><a class="toc-backref" href="#id21">How can I eliminate clone wars?</a><a class="headerlink" href="#how-can-i-eliminate-clone-wars" title="Permalink to this heading">¶</a></h3>
<p>Clone wars can be most annoying. The solution is simple:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">**</span><span class="n">Keep</span> <span class="n">clones</span> <span class="n">only</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">outline</span> <span class="ow">and</span> <span class="ow">in</span> <span class="n">one</span> <span class="n">other</span> <span class="n">external</span> <span class="n">file</span><span class="o">**</span>
</pre></div>
</div>
<p>In particular, catchall files like leo/doc/leoProjects.txt or leo/doc/leoToDo.txt should never contain clones.</p>
</section>
<section id="how-can-i-use-clones-to-reorganize-an-outline">
<h3><a class="toc-backref" href="#id22">How can I use clones to reorganize an outline?</a><a class="headerlink" href="#how-can-i-use-clones-to-reorganize-an-outline" title="Permalink to this heading">¶</a></h3>
<p>Clones make reorganizing an outline significantly easier and faster.  Simply make top-level clones of the nodes you keep encountering during the reorg. This makes moving a node a snap: just move it from one clone to another.</p>
</section>
<section id="how-does-ekr-use-clones">
<h3><a class="toc-backref" href="#id23">How does EKR use clones?</a><a class="headerlink" href="#how-does-ekr-use-clones" title="Permalink to this heading">¶</a></h3>
<p>For the last several weeks I’ve used clones in a new, more effective way, inspired by git’s stash/unstash commands. Here are the main ideas.</p>
<ol class="arabic simple">
<li><p>[Most important] I avoid putting clones in two different <em>external</em> files.</p></li>
</ol>
<p>For any task, I create a task node that resides in &#64;file leoToDo.txt. I clone that node and put it in the outline, <em>never</em> in any other &#64;file node. This instantly eliminates clone wars.</p>
<ol class="arabic simple" start="2">
<li><p>I use top-level “stashed” nodes/trees in my local copy of leoPy.leo.</p></li>
</ol>
<p>These clones are <em>not</em> written to any external file, so they would be lost if I lost leoPy.leo. But the risks are negligible because all stashed nodes are clones of nodes that <em>do</em> exist in external files.</p>
<ol class="arabic simple" start="3">
<li><p>I have two main stashed trees: recent files and recent code.</p></li>
</ol>
<p>The “recent files” tree contains clones of all the &#64;file nodes I have worked on recently. This speeds up access to them. That happens surprisingly often–often enough to be well worth maintaining the tree. Furthermore, because Leo’s new pylint command now works on trees, I can check all recently-changed files simply by running pylint on the “recent files” tree.</p>
<p>The “recent code” tree is even more valuable, for three reasons. The first is obvious–it speeds access to recently-changed nodes.</p>
<p>Second, the “recent code” tree allows me to work on multiple tasks without getting overwhelmed by details and loose nodes lying around. I add organizer nodes as needed to make accessing the nodes faster, and also to jog my memory about what I was doing when I changed those nodes ;-)</p>
<p>Third, the “recent code” tree allows me <em>not</em> to put clones in the &#64;file leoProjects.txt tree. This leads me to…</p>
<ol class="arabic simple" start="4">
<li><p>I use clones in a stylized way when fixing and committing bugs.</p></li>
</ol>
<p>I always use clones when working on a project. A “task” node contains clones of all nodes related to the task. The task node typically remains in leoToDo.txt until the task is completely finished. While working on the bug, I create a clone of the task node, and move that clone to the bottom top-level node of the outline. Among other things, this makes it easy to limit searches without actually choosing “suboutline only” in the Find panel. This workflow is decades old.</p>
<p>The following is the heart of the new workflow. When a task is complete, I do the following:</p>
<ol class="upperalpha simple">
<li><p>First, I create a <strong>stashed-task</strong> node, containing all the clones that were previously in the task node.</p></li>
</ol>
<p>The <em>stashed-task</em> becomes pre-writing for the commit log. The <em>task</em> node instantly becomes pre-writing for the release notes, so if it needs to discuss any code in the clones that have just been moved to the stashed-task node, I write those words immediately, while all details are fresh in my mind.</p>
<ol class="upperalpha simple" start="2">
<li><p>Now I move the cloned task node that is in leoToDo.txt to the appropriate place in leoProjects.txt.</p></li>
<li><p>Next I do the commit.</p></li>
</ol>
<p>The <em>other</em> clone of the task node, and the stashed task node are still within easy reach, and I typically use both nodes to create the commit log. The commit will typically consist of the changed leoToDo.txt and leoProjects.txt and whatever .py files the task itself changed. Happily, leoToDo.txt and leoProjects.txt are now up-to-date because of steps A and B.</p>
<ol class="upperalpha simple" start="4">
<li><p>Finally, I clean up.</p></li>
</ol>
<p>I delete the top-level clone of the task node, and move the stashed-task
node to the “recent code” tree.</p>
<ol class="upperalpha simple" start="5">
<li><p>Later, when it appears that activity has died down on various projects, I’ll delete nodes from the “recent files” an “recent code” trees. This is a minor judgment call: I want to leave nodes in the trees while they are useful, but not significantly longer than that. I do <em>not</em> regard these trees as permanently useful. leoProjects.txt should contain <em>all</em> permanent notes about a project.</p></li>
</ol>
<p>===== Conclusions</p>
<p>This work flow may seem complicated. Believe me, it is not. It’s easier to use than to describe.</p>
<p>This workflow has big advantages:</p>
<ol class="arabic simple">
<li><p>Clone wars are gone for good.</p></li>
<li><p>All recent data is easily available.</p></li>
<li><p>Task nodes and stashed-task nodes provide natural places for proto-documentation.</p></li>
<li><p>Banning clones from leoProjects.txt forces me to complete the first draft of the documentation before committing the fix.</p></li>
</ol>
</section>
<section id="how-does-leo-handle-clone-conflicts">
<h3><a class="toc-backref" href="#id24">How does Leo handle clone conflicts?</a><a class="headerlink" href="#how-does-leo-handle-clone-conflicts" title="Permalink to this heading">¶</a></h3>
<p>Some people seem to think that it is difficult to understand how Leo handles “clone wars”: differing values for a cloned nodes that appear in several external files. That’s not true. The rule is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">**</span><span class="n">The</span> <span class="n">last</span> <span class="n">clone</span> <span class="n">that</span> <span class="n">Leo</span> <span class="n">reads</span> <span class="n">wins</span><span class="o">.**</span>
</pre></div>
</div>
<p>That is, for any cloned node C, Leo takes the value of C.h and C.b to be the values specified by the last copy that Leo reads.</p>
<p>There is only one complication:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">**</span><span class="n">Leo</span> <span class="n">reads</span> <span class="n">the</span> <span class="n">entire</span> <span class="n">outline</span> <span class="n">before</span> <span class="n">reading</span> <span class="nb">any</span> <span class="n">external</span> <span class="n">files</span><span class="o">.**</span>
</pre></div>
</div>
<p>Thus, if C appears in x.leo, y.py and z.py, Leo will choose the value for C in x.py or y.py, depending on which &#64;&lt;file&gt; node appears later in the outline.</p>
<p><strong>Note</strong>: Whenever Leo detects multiple values for C when opening an outline, Leo creates a “Recovered nodes” tree. This tree contains all the various values for C, nicely formatted so that it is easy to determine where the differences are.</p>
</section>
<section id="when-is-deleting-a-node-dangerous">
<h3><a class="toc-backref" href="#id25">When is deleting a node dangerous?</a><a class="headerlink" href="#when-is-deleting-a-node-dangerous" title="Permalink to this heading">¶</a></h3>
<p>A <strong>dangerous</strong> delete is a deletion of a node so that all the data in the node is deleted <em>everywhere</em> in an outline. The data is gone, to be retrieved only via undo or via backups. It may not be obvious which deletes are dangerous in an outline containing clones. Happily, there is a very simple rule of thumb:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Deleting</span> <span class="n">a</span> <span class="n">non</span><span class="o">-</span><span class="n">cloned</span> <span class="n">node</span> <span class="ow">is</span> <span class="o">*</span><span class="n">always</span><span class="o">*</span> <span class="n">dangerous</span><span class="o">.</span>
<span class="n">Deleting</span> <span class="n">a</span> <span class="n">cloned</span> <span class="n">node</span> <span class="ow">is</span> <span class="o">*</span><span class="n">never</span><span class="o">*</span> <span class="n">dangerous</span><span class="o">.</span>
</pre></div>
</div>
<p>We could also consider a delete to be dangerous <strong>if it results in a node being omitted from an external file.</strong> This can happen as follows. Suppose we have the following outline (As usual, A’ indicates that A is marked with a clone mark):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span> <span class="nd">@file</span> <span class="n">spam</span><span class="o">.</span><span class="n">py</span>
    <span class="o">-</span> <span class="n">A</span><span class="s1">&#39;</span>
        <span class="o">-</span> <span class="n">B</span>
<span class="o">-</span> <span class="n">Projects</span>
    <span class="o">-</span> <span class="n">A</span><span class="s1">&#39;</span>
        <span class="o">-</span> <span class="n">B</span>
</pre></div>
</div>
<p>Now suppose we clone B, and move the clone so the tree looks like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span> <span class="nd">@file</span> <span class="n">spam</span><span class="o">.</span><span class="n">py</span>
    <span class="o">-</span> <span class="n">A</span><span class="s1">&#39;</span>
        <span class="o">-</span> <span class="sa">B</span><span class="s1">&#39;</span>
<span class="o">-</span> <span class="n">Projects</span>
    <span class="o">-</span> <span class="n">A</span><span class="s1">&#39;</span>
        <span class="o">-</span> <span class="sa">B</span><span class="s1">&#39;</span>
    <span class="o">-</span> <span class="sa">B</span><span class="s1">&#39;</span>
</pre></div>
</div>
<p>If (maybe much later), we eliminate B’ as a child of A will get:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span> <span class="nd">@file</span> <span class="n">spam</span><span class="o">.</span><span class="n">py</span>
    <span class="o">-</span> <span class="n">A</span><span class="s1">&#39;</span>
<span class="o">-</span> <span class="n">Projects</span>
    <span class="o">-</span> <span class="n">A</span><span class="s1">&#39;</span>
    <span class="o">-</span> <span class="n">B</span>
</pre></div>
</div>
<p>B has not been destroyed, but B is gone from &#64;file spam.py! So in this sense deleting a clone node can also be called dangerous.</p>
</section>
<section id="when-may-i-delete-clones-safely">
<h3><a class="toc-backref" href="#id26">When may I delete clones safely?</a><a class="headerlink" href="#when-may-i-delete-clones-safely" title="Permalink to this heading">¶</a></h3>
<p>Q: When can I delete a clone safely?</p>
<p>A: Any time! The only time you can “lose” data is when you delete a non-cloned node, save your work and exit Leo.</p>
<p>Q: What gets “lost” when I delete a non-cloned node?</p>
<p>A: The node, and all it’s non-cloned children. In addition, if the node contains all clones of a cloned node, all copies of the cloned node will also be “lost”.</p>
<p>Q: Anything else I should be careful about concerning clones?</p>
<p>Not really.  If you move any node out “underneath” an &#64;file (&#64;clean, etc) node, the contents of that node disappears from the external file.</p>
<p>I hope this encourages more people to use clones.  Leo’s clone-find commands are something that every Leo programmers should be using every day.</p>
</section>
<section id="why-doesn-t-leo-support-cross-outline-clones">
<h3><a class="toc-backref" href="#id27">Why doesn’t Leo support cross-outline clones?</a><a class="headerlink" href="#why-doesn-t-leo-support-cross-outline-clones" title="Permalink to this heading">¶</a></h3>
<p>Any outline (.leo file) may contain clones that appear in multiple external files defined <em>within</em> that outline. There is no problem with such <strong>intra-outline clones</strong>.</p>
<p>In contrast, <strong>cross-outline clones</strong> are clones that appear in more than one outline.  Leo’s paste-retaining-clones command makes it possible for two outlines to contain nodes with the same gnx. Conceivably, both outlines could use those clones in the <em>same</em> external file!</p>
<p>Leo will never encourage cross-outline clones, because such clones are inherently dangerous. Indeed, neither outline would have full responsibility for its own data.</p>
<p>Indeed, the shared clones would be subject to the well-known multiple-update problem. Suppose the two outlines were open simultaneously, and each outline changed the shared clones in different ways. Whichever outline changed the data last would “win.” The changes in the other outline would be lost forever!</p>
<p>In short, Leo will never support features that encourage cross-outline clones.</p>
</section>
<section id="why-is-alt-n-goto-next-clone-important">
<h3><a class="toc-backref" href="#id28">Why is Alt-N (goto-next-clone) important?</a><a class="headerlink" href="#why-is-alt-n-goto-next-clone-important" title="Permalink to this heading">¶</a></h3>
<p>clone-find-all-flattened often includes clones of nodes whose location is unclear.  No problem! Just select the mysterious node and do Alt-N (goto-next-clone). Leo will select the next clone of that node, wrapping the search as necessary.  One or two Alt-N takes me to the “real” node, the node having an ancestor &#64;&lt;file&gt; node.</p>
<p>Ideally, the meaning of all nodes would be clear from their headlines.  I typically use the following conventions. For section definitions, the headline should contain file or class name.  Examples:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&lt;&lt;</span> <span class="n">imports</span> <span class="o">&gt;&gt;</span> <span class="p">(</span><span class="n">leoCommands</span><span class="o">.</span><span class="n">py</span><span class="p">)</span>
<span class="o">&lt;&lt;</span> <span class="n">docstring</span> <span class="o">&gt;&gt;</span> <span class="p">(</span><span class="n">LeoApp</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="why-should-i-use-clones">
<h3><a class="toc-backref" href="#id29">Why should I use clones?</a><a class="headerlink" href="#why-should-i-use-clones" title="Permalink to this heading">¶</a></h3>
<p>You will lose much of Leo’s power if you don’t use clones. See <a class="reference external" href="tutorial-pim.html#clones">Clones</a> and <a class="reference external" href="tutorial-pim.html#views">Views</a> for full details.</p>
</section>
</section>
<section id="customizing-leo">
<h2><a class="toc-backref" href="#id30">Customizing Leo</a><a class="headerlink" href="#customizing-leo" title="Permalink to this heading">¶</a></h2>
<section id="how-can-i-create-a-pane-for-matplotlib-charts">
<h3><a class="toc-backref" href="#id31">How can I create a pane for matplotlib charts?</a><a class="headerlink" href="#how-can-i-create-a-pane-for-matplotlib-charts" title="Permalink to this heading">¶</a></h3>
<p>I’m trying to create a interactive chart in a embedded in a new leo pane using matplotlib. However, I am not sure about the the best way to implement this. I would appreciate some guidance on this please? The questions I would like answered are:</p>
<ol class="arabic simple">
<li><p>How do I create a new blank pane for embedding a chart as well as other QtWidgets.</p></li>
<li><p>Can I do this in a script or do I need to work with leo source?</p></li>
</ol>
<p>I want to create a data processing and visualization tool kit in leo. Like Excel but using nodes instead of columns. Nodes will have data and I want to create new data nodes by applying python functions to data in existing nodes. The thing missing is the visualization within a leo pane (I can easily launch a chart in it’s own window).</p>
<p><strong>Terry Brown</strong></p>
<p>You can run this script from any body pane:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="sd">&#39;&#39;&#39;</span>
<span class="sd">A script that adds a MatPlotLib pane to Leo.</span>

<span class="sd">After running this script, right click on one of the pane dividers and</span>
<span class="sd">select Insert. A new pane with a button &#39;Action&#39; appears. Click it, and</span>
<span class="sd">select &quot;Add matplot&quot; from the context menu.</span>
<span class="sd">&#39;&#39;&#39;</span>

<span class="kn">from</span> <span class="nn">leo.core.leoQt</span> <span class="kn">import</span> <span class="n">QtWidgets</span>

<span class="k">class</span> <span class="nc">MatplotPaneProvider</span><span class="p">:</span>
    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">c</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">c</span> <span class="o">=</span> <span class="n">c</span>
        <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">c</span><span class="p">,</span> <span class="s1">&#39;free_layout&#39;</span><span class="p">):</span>
            <span class="n">splitter</span> <span class="o">=</span> <span class="n">c</span><span class="o">.</span><span class="n">free_layout</span><span class="o">.</span><span class="n">get_top_splitter</span><span class="p">()</span>
            <span class="k">if</span> <span class="n">splitter</span><span class="p">:</span>
                <span class="n">splitter</span><span class="o">.</span><span class="n">register_provider</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">ns_provides</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span><span class="p">[(</span><span class="s1">&#39;Add matplot&#39;</span><span class="p">,</span> <span class="s1">&#39;_add_matplot_pane&#39;</span><span class="p">)]</span>
    <span class="k">def</span> <span class="nf">ns_provide</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">id_</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">id_</span> <span class="o">==</span> <span class="s1">&#39;_add_matplot_pane&#39;</span><span class="p">:</span>
            <span class="n">c</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">c</span>
            <span class="n">w</span> <span class="o">=</span> <span class="n">QtWidgets</span><span class="o">.</span><span class="n">QSlider</span><span class="p">()</span> <span class="c1">### w = myMatplotWidget()</span>
            <span class="k">return</span> <span class="n">w</span>
    <span class="k">def</span> <span class="nf">ns_provider_id</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="c1"># used by register_provider() to unregister previously registered</span>
        <span class="c1"># providers of the same service</span>
        <span class="c1"># provider ID is not the same as the service id_ above</span>
        <span class="k">return</span> <span class="s2">&quot;completely unique value here&quot;</span>

<span class="n">MatplotPaneProvider</span><span class="p">(</span><span class="n">c</span><span class="p">)</span>
</pre></div>
</div>
<p><strong>OP</strong></p>
<p>I have managed to get a matplotlib graph embedded within a pane in leo as a widget. I now need some help with how to interact with the widget using scripts in leo. I am unsure about the following:</p>
<p><em>1/ How do I expose the widget within the leo environment?</em></p>
<p>If you were only going to have one and you weren’t going to destroy it, you could just do something simple like c._matplot = self in its constrictor (assuming c was passed to the constructor).</p>
<p>If you’re going to have more than one and they may be destroyed, it might be simplest to let the free_layout / nested_splitter system manage them:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ts</span> <span class="o">=</span> <span class="n">c</span><span class="o">.</span><span class="n">free_layout</span><span class="o">.</span><span class="n">get_top_splitter</span><span class="p">()</span>
<span class="n">matplotters</span> <span class="o">=</span> <span class="n">ts</span><span class="o">.</span><span class="n">findChildren</span><span class="p">(</span><span class="n">myMatplotWidget</span><span class="p">)</span>
</pre></div>
</div>
<p>should return a list of the widgets of your class in the layout, but only if they’re in the main window, widgets in extra windows opened from the “Open window” context menu item would be missed, I can add a find_children() method to complement the find_child() method the splitters already have to account for this.</p>
<p>Detail: the above is just using Qt’s QObject.findChildren(), the nested_splitter find_child() and (not yet written) find_children() versions search the extra windows as well.</p>
<p>Here I have created a self.mat in your MatplotPaneProvider class to make the widget accessible but it doesn’t feel like the correct way to do this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mat</span> <span class="o">=</span> <span class="n">MatplotPaneProvider</span><span class="p">(</span><span class="n">c</span><span class="p">)</span>
<span class="n">mat</span><span class="o">.</span><span class="n">mat</span><span class="o">.</span><span class="n">someMethod</span><span class="p">()</span>
<span class="n">mat</span><span class="o">.</span><span class="n">mat</span><span class="o">.</span><span class="n">someOtherMethod</span><span class="p">()</span>
</pre></div>
</div>
<ol class="arabic simple" start="2">
<li><p>I would also like to make the widget accessible from any script within leo. What’s the leo way of doing this?</p></li>
</ol>
<p>See above</p>
<ol class="arabic simple" start="3">
<li><p>If I create more than 1 pane containing these widgets. How do I switch between them in scripts?</p></li>
</ol>
<p>See above</p>
<ol class="arabic simple" start="4">
<li><p>Running this script more than once creates multiple items for Add Matplot when pressing the Action button. How do I stop this from happening? I have already tried returning a unique integer in * ns_provider_id <em>but that did not work.</em></p></li>
</ol>
<p>The value returned by ns_provider_id should be unique for the provider class, but constant. So it can just return something like “matplotlib provider ver 1”</p>
</section>
<section id="how-can-i-customize-settings-for-a-particular-external-file">
<h3><a class="toc-backref" href="#id32">How can I customize settings for a particular external file?</a><a class="headerlink" href="#how-can-i-customize-settings-for-a-particular-external-file" title="Permalink to this heading">¶</a></h3>
<p>How it is possible to specify settings in &#64;file? As I understand every setting should be a single outline.</p>
<p>Vitalije:</p>
<p>You can use clones. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--</span><span class="nd">@settings</span>
<span class="o">----</span><span class="n">my</span><span class="o">-</span><span class="n">shared</span><span class="o">-</span><span class="n">settings</span>
<span class="o">------...</span>
<span class="o">----</span><span class="n">some</span><span class="o">-</span><span class="n">specific</span><span class="o">-</span><span class="n">settings</span><span class="o">-</span><span class="k">for</span><span class="o">-</span><span class="n">this</span><span class="o">-</span><span class="n">outline</span>
<span class="o">------....</span>

<span class="o">--</span><span class="nd">@file</span> <span class="n">my</span><span class="o">-</span><span class="n">shared</span><span class="o">-</span><span class="n">settings</span><span class="o">-</span><span class="n">somewhere</span><span class="o">.</span><span class="n">txt</span>
<span class="o">----</span><span class="n">my</span><span class="o">-</span><span class="n">shared</span><span class="o">-</span><span class="n">settings</span>
</pre></div>
</div>
<p>where <cite>my-shared-settings</cite> node is cloned from the &#64;file subtree.</p>
<p>Quite often I use some script to combine some nodes, process them and generate some output file. And such script I put in a node with the following headline: <cite>&#64;button n-save &#64;key=Ctrl-s</cite>. Then whenever I open this outline and whenever I hit Ctrl-s to save the outline, this script is executed. Of course I put in this script <cite>c.save()</cite> call and on every save my files are regenerated.</p>
<p>When working for a web I often use Coffeescript, some html template generators like Pug, Sass for generating css files, … Now all of these command line tools have watching mode where they watch folders for file changes and whenever source file is changed they regenerate the output file. But then you also need to run some packaging tool to bundle all generated files. Instead of watching for file changes, my script bound to Ctrl-s regenerate source files in memory and without saving them execute suitable tool only on changed sources and produced outputs bundle in the final file. This makes the whole process much faster.</p>
<p>Attached to this message is a Leo file that I have extracted from one of my projects. I hope that I didn’t miss anything that the script require.</p>
<p>In the outline you can find build server implemented in Coffeescript. You have to use npm or yarn to install necessary modules for this server to work. Once installed you start server by executing
<cite>coffee tools/build-server.coffee</cite> and it will start listening on port 8011. The script bound to Ctrl-s will search outline for nodes with the headlines like: &#64;vendor, &#64;pug, &#64;coffee, &#64;bulma and for each found node, it checks if the content of this node and its subtree has changed since last time and if it is, this content is sent to build server which transforms the source and returns result that script writes to output file.</p>
<p>There is one more thing I use for sharing outlines. There are three commands <cite>set-reference-file</cite>, <cite>update-ref-file</cite> and <cite>read-ref-file</cite>. The first lets you choose a reference file for this outline, i.e. public shared outline. It adds a top level headline <cite>—begin-private-area—</cite> to the outline. In the body of this node is the path to the public Leo file. Everything below this node is private, and above is public. The public file should be added to version control (git, fossil,…) and the private file should be added to ignored files for version control tool. And then in the script bound to Ctrl-s you can add <cite>c.fileCommands.save_ref()</cite>, so every time you save your private Leo file, at the same time is updated the public Leo file. That way they never get out of sync.</p>
</section>
<section id="how-can-i-enable-and-disable-support-for-psyco">
<h3><a class="toc-backref" href="#id33">How can I enable and disable support for psyco?</a><a class="headerlink" href="#how-can-i-enable-and-disable-support-for-psyco" title="Permalink to this heading">¶</a></h3>
<p>Find the &#64;file leoApp.py node in leoPy.leo. In the ctor for the LeoApp class set self.use_psyco to True or False. You will find this ctor in the node:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Code</span><span class="o">--&gt;</span><span class="n">Core</span> <span class="n">classes</span><span class="o">...--&gt;</span><span class="nd">@file</span> <span class="n">leoApp</span><span class="o">.</span><span class="n">py</span><span class="o">--&gt;</span><span class="n">app</span><span class="o">.</span><span class="fm">__init__</span>
</pre></div>
</div>
<p>Note that this ivar can not be set using settings in leoSettings.leo because Leo uses g.app.use_psyco before processing configuration settings.</p>
</section>
<section id="how-can-i-modify-an-existing-theme">
<h3><a class="toc-backref" href="#id34">How can I modify an existing theme?</a><a class="headerlink" href="#how-can-i-modify-an-existing-theme" title="Permalink to this heading">¶</a></h3>
<p>In the directory leo-editor/leo/themes are a number of theme files. These
can be loaded using the File, Open Outline menu option in Leo. Opening an
outline automatically loads it. Keep opening outlines until you find one
you like.</p>
<p>Then close all of the theme files.</p>
<p>Copy the theme file you chose from leo-editor/leo/themes to ~/.leo/themes
(you will have to create the themes folder here) and rename it something
like this: Original file is BreezeDarkTheme.leo rename to
BreezeDarkThemeLocal.leo</p>
<p>Now open your myLeoSettings.leo file.</p>
<p>Add the following to the headline of a new node as a child of your &#64;settings node:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@string</span> <span class="n">theme</span><span class="o">-</span><span class="n">name</span> <span class="o">=</span> <span class="n">BreezeDarkThemeLocal</span>
</pre></div>
</div>
<p>Now save the file and restart Leo.</p>
<p>You should now be using the theme of your choice. From here you need to
open the local theme file with Leo. The font sizing and colors are under
Theme Settings in the tree.</p>
</section>
<section id="how-can-i-put-background-images-in-the-body-pane">
<h3><a class="toc-backref" href="#id35">How can I put background images in the body pane?</a><a class="headerlink" href="#how-can-i-put-background-images-in-the-body-pane" title="Permalink to this heading">¶</a></h3>
<p>Put the following in the style-sheet:</p>
<blockquote>
<div><p>QTextEdit#richTextEdit { background-image: url(‘/home/tbrown/Desktop/cow2.jpg’); }</p>
</div></blockquote>
<p>If you wanted node specific backgrounds Leo would have to start setting an attribute on the body widget, probably the gnx, so you could do:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">QTextEdit</span><span class="c1">#richTextEdit[leo_gnx=&#39;tbrown.20130430222443.19340&#39;] {</span>
    <span class="n">background</span><span class="o">-</span><span class="n">image</span><span class="p">:</span> <span class="n">url</span><span class="p">(</span><span class="s1">&#39;/home/tbrown/Desktop/cow2.jpg&#39;</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
</section>
<section id="how-can-i-run-code-at-startup">
<h3><a class="toc-backref" href="#id36">How can I run code at startup?</a><a class="headerlink" href="#how-can-i-run-code-at-startup" title="Permalink to this heading">¶</a></h3>
<p>The following plugin, placed in ~/.leo/plugins, runs code at ‘start1’ time, that is, while other plugins are loading:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">leo.core.leoGlobals</span> <span class="k">as</span> <span class="nn">g</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">&#39;===== local_plugin.py in ~/.leo/plugins/&#39;</span><span class="p">)</span>

<span class="k">def</span> <span class="nf">hook</span><span class="p">(</span><span class="n">tag</span><span class="p">,</span> <span class="n">keys</span><span class="p">):</span>
    <span class="n">g</span><span class="o">.</span><span class="n">trace</span><span class="p">(</span><span class="n">tag</span><span class="p">)</span>

<span class="k">def</span> <span class="nf">init</span><span class="p">():</span>
    <span class="n">g</span><span class="o">.</span><span class="n">registerHandler</span><span class="p">(</span><span class="s1">&#39;start1&#39;</span><span class="p">,</span> <span class="n">hook</span><span class="p">)</span>
    <span class="k">return</span> <span class="kc">True</span>
</pre></div>
</div>
<p>Alternatively, the plugin could run code at ‘start2’ time, after all plugins have been loaded, or at any other time, as described <a class="reference external" href="writingPlugins.html#handling-events">on this page</a>.</p>
</section>
<section id="how-can-i-sync-settings-across-leo-files">
<h3><a class="toc-backref" href="#id37">How can I sync settings across .leo files?</a><a class="headerlink" href="#how-can-i-sync-settings-across-leo-files" title="Permalink to this heading">¶</a></h3>
<p>Organize your myLeoSettings.leo file like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@settings</span>
     <span class="o">-</span><span class="n">my</span> <span class="n">settings</span> <span class="o">&lt;</span><span class="n">clone</span><span class="o">&gt;</span>
          <span class="o">-</span><span class="nd">@bool</span> <span class="o">....</span> <span class="o">=</span> <span class="kc">True</span>
          <span class="o">-</span><span class="nd">@data</span> <span class="n">fldsdf</span>

<span class="nd">@file</span> <span class="n">mysettings</span><span class="o">.</span><span class="n">txt</span>
      <span class="n">my</span> <span class="n">settings</span> <span class="o">&lt;</span><span class="n">clone</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>Syncing mySettings.txt will synchronize your settings across your .leo files.</p>
<p><strong>Note</strong>: Changed settings will not be available in other open outlines until you reload settings. You can do this with the reload-all-settings command.</p>
</section>
<section id="how-do-i-enable-a-theme-leo-file">
<h3><a class="toc-backref" href="#id38">How do I enable a theme .leo file?</a><a class="headerlink" href="#how-do-i-enable-a-theme-leo-file" title="Permalink to this heading">¶</a></h3>
<p>To enable a theme .leo file, put the following setting in myLeoSettings.leo:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@string</span> <span class="n">theme</span><span class="o">-</span><span class="n">name</span> <span class="o">=</span> <span class="o">&lt;</span><span class="n">theme</span> <span class="n">file</span><span class="p">,</span> <span class="n">without</span> <span class="n">the</span> <span class="o">.</span><span class="n">leo</span> <span class="n">extension</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>Dark themes:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@string</span> <span class="n">theme</span><span class="o">-</span><span class="n">name</span> <span class="o">=</span> <span class="n">BreezeDarkTheme</span>
<span class="nd">@string</span> <span class="n">theme</span><span class="o">-</span><span class="n">name</span> <span class="o">=</span> <span class="n">EKRDark</span>
<span class="nd">@string</span> <span class="n">theme</span><span class="o">-</span><span class="n">name</span> <span class="o">=</span> <span class="n">LeoBlackSolarized</span>
<span class="nd">@string</span> <span class="n">theme</span><span class="o">-</span><span class="n">name</span> <span class="o">=</span> <span class="n">ZephyrDarkTheme</span>
</pre></div>
</div>
<p>Light themes:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@string</span> <span class="n">theme</span><span class="o">-</span><span class="n">name</span> <span class="o">=</span> <span class="n">DefaultTheme</span>
<span class="nd">@string</span> <span class="n">theme</span><span class="o">-</span><span class="n">name</span> <span class="o">=</span> <span class="n">EKRLight</span>
<span class="nd">@string</span> <span class="n">theme</span><span class="o">-</span><span class="n">name</span> <span class="o">=</span> <span class="n">PaperLightTheme</span>
</pre></div>
</div>
<p>You can also define a theme directly in myLeoSettings.leo as follows:</p>
<ul class="simple">
<li><p><em>Remove</em> (or disable) any previous &#64;theme tree in myLeoSettings.leo.</p></li>
<li><p><em>Select</em> one of the &#64;theme trees in leoSettings.leo.</p></li>
<li><p><em>Copy</em> the entire &#64;theme tree to myLeoSettings.leo.</p></li>
<li><p><em>Move</em> the copied tree to the <em>end</em> of the &#64;settings tree.</p></li>
<li><p><em>Test</em> by restarting Leo.</p></li>
</ul>
</section>
<section id="how-can-i-use-leo-s-legacy-key-bindings">
<h3><a class="toc-backref" href="#id39">How can I use Leo’s legacy key bindings?</a><a class="headerlink" href="#how-can-i-use-leo-s-legacy-key-bindings" title="Permalink to this heading">¶</a></h3>
<p>You can ‘revert’ to old key bindings as follows:</p>
<ol class="arabic simple">
<li><p>Open leoSettings.leo.</p></li>
<li><p>Find the node ‘Keyboard shortcuts’.</p></li>
<li><p>Disable the old bindings by moving the node <a class="reference external" href="mailto:'&#37;&#52;&#48;keys">‘<span>&#64;</span>keys</a> EKR bindings: Emacs keys + modes’ so that it is a child of the node: <a class="reference external" href="mailto:'&#37;&#52;&#48;ignore">‘<span>&#64;</span>ignore</a> Unused key bindings’.</p></li>
<li><p>Notice that there are two child nodes of the node <a class="reference external" href="mailto:'&#37;&#52;&#48;ignore">‘<span>&#64;</span>ignore</a> Unused key bindings’ that refer to legacy key bindings:</p>
<ul class="simple">
<li><p><a class="reference external" href="mailto:'&#37;&#52;&#48;keys">‘<span>&#64;</span>keys</a> Legacy Leo shortcuts with important Emacs bindings’</p></li>
<li><p><a class="reference external" href="mailto:'&#37;&#52;&#48;keys">‘<span>&#64;</span>keys</a> Legacy Leo bindings’.</p></li>
</ul>
</li>
<li><p>Move <strong>one</strong> of these two legacy nodes up one level so that it is a child of the node ‘Keyboard shortcuts’. It should <strong>not</strong> be a child of the node <a class="reference external" href="mailto:'&#37;&#52;&#48;ignore">‘<span>&#64;</span>ignore</a> Unused key bindings’.</p></li>
</ol>
</section>
<section id="how-do-i-add-a-new-menu-item-from-a-plugin">
<h3><a class="toc-backref" href="#id40">How do I add a new menu item from a plugin?</a><a class="headerlink" href="#how-do-i-add-a-new-menu-item-from-a-plugin" title="Permalink to this heading">¶</a></h3>
<p>c.frame.menu.createMenuItemsFromTable will append items to the end of an existing menu. For example, the following script will add a new item at the end of the ‘File’ menu:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">callback</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span><span class="o">**</span><span class="n">keys</span><span class="p">):</span>
    <span class="n">g</span><span class="o">.</span><span class="n">trace</span><span class="p">()</span>

<span class="n">table</span> <span class="o">=</span> <span class="p">((</span><span class="s2">&quot;Test1&quot;</span><span class="p">,</span><span class="kc">None</span><span class="p">,</span><span class="n">callback</span><span class="p">),)</span>

<span class="n">c</span><span class="o">.</span><span class="n">frame</span><span class="o">.</span><span class="n">menu</span><span class="o">.</span><span class="n">createMenuItemsFromTable</span><span class="p">(</span><span class="s1">&#39;File&#39;</span><span class="p">,</span><span class="n">table</span><span class="p">)</span>
</pre></div>
</div>
<p>Plugins can do anything with menus using c.frame.menu.getMenu. For example, here is a script that adds a Test menu item after the ‘Open With’ menu item in the File menu:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">callback</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span><span class="o">**</span><span class="n">keys</span><span class="p">):</span>
    <span class="n">g</span><span class="o">.</span><span class="n">trace</span><span class="p">()</span>

<span class="n">fileMenu</span> <span class="o">=</span> <span class="n">c</span><span class="o">.</span><span class="n">frame</span><span class="o">.</span><span class="n">menu</span><span class="o">.</span><span class="n">getMenu</span><span class="p">(</span><span class="s1">&#39;File&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p># 3 is the position in the menu.  Other kinds of indices are possible:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">fileMenu</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="s1">&#39;command&#39;</span><span class="p">,</span><span class="n">label</span><span class="o">=</span><span class="s1">&#39;Test2&#39;</span><span class="p">,</span><span class="n">command</span><span class="o">=</span><span class="n">callback</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="how-do-i-set-selection-colors">
<h3><a class="toc-backref" href="#id41">How do I set selection colors?</a><a class="headerlink" href="#how-do-i-set-selection-colors" title="Permalink to this heading">¶</a></h3>
<p>You set most colors in the following settings node:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@data</span> <span class="n">qt</span><span class="o">-</span><span class="n">gui</span><span class="o">-</span><span class="n">plugin</span><span class="o">-</span><span class="n">style</span><span class="o">-</span><span class="n">sheet</span>
</pre></div>
</div>
<p>However, settings for colors that can change during Leo’s execution are found in the node:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Body</span> <span class="n">pane</span> <span class="n">colors</span>
</pre></div>
</div>
<p>These settings are as follows, with the defaults as shown:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@color</span> <span class="n">body_cursor_background_color</span> <span class="o">=</span> <span class="kc">None</span>
<span class="nd">@color</span> <span class="n">body_cursor_foreground_color</span> <span class="o">=</span> <span class="kc">None</span>
<span class="nd">@color</span> <span class="n">body_insertion_cursor_color</span> <span class="o">=</span> <span class="kc">None</span>
<span class="nd">@color</span> <span class="n">body_text_background_color</span> <span class="o">=</span> <span class="kc">None</span>
<span class="nd">@color</span> <span class="n">body_text_foreground_color</span> <span class="o">=</span> <span class="kc">None</span>
<span class="nd">@color</span> <span class="n">command_mode_bg_color</span> <span class="o">=</span> <span class="c1">#f2fdff</span>
<span class="nd">@color</span> <span class="n">command_mode_fg_color</span> <span class="o">=</span> <span class="kc">None</span>
<span class="nd">@color</span> <span class="n">insert_mode_bg_color</span> <span class="o">=</span> <span class="c1">#fdf5f5</span>
<span class="nd">@color</span> <span class="n">insert_mode_fg_color</span> <span class="o">=</span> <span class="n">black</span>
<span class="nd">@color</span> <span class="n">overwrite_mode_bg_color</span> <span class="o">=</span> <span class="n">azure2</span>
<span class="nd">@color</span> <span class="n">overwrite_mode_fg_color</span> <span class="o">=</span> <span class="n">black</span>
<span class="nd">@color</span> <span class="n">unselected_body_bg_color</span> <span class="o">=</span> <span class="c1">#ffffef</span>
<span class="nd">@color</span> <span class="n">unselected_body_fg_color</span> <span class="o">=</span> <span class="n">black</span>
</pre></div>
</div>
</section>
<section id="how-do-i-specify-qt-fonts">
<h3><a class="toc-backref" href="#id42">How do I specify qt fonts?</a><a class="headerlink" href="#how-do-i-specify-qt-fonts" title="Permalink to this heading">¶</a></h3>
<p>When using the Qt gui, you specify fonts using the node in leoSettings.leo called:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@data</span> <span class="n">qt</span><span class="o">-</span><span class="n">gui</span><span class="o">-</span><span class="n">plugin</span><span class="o">-</span><span class="n">style</span><span class="o">-</span><span class="n">sheet</span>
</pre></div>
</div>
<p>As usual, you will probably want to put this node in your myLeoSettings.leo file.</p>
</section>
<section id="how-do-i-submit-a-plugin">
<h3><a class="toc-backref" href="#id43">How do I submit a plugin?</a><a class="headerlink" href="#how-do-i-submit-a-plugin" title="Permalink to this heading">¶</a></h3>
<p>You have two options:</p>
<ul class="simple">
<li><p>Get git write access, and add the &#64;file file to the plugins directory.</p></li>
<li><p>Just send the &#64;file file to me at <a class="reference external" href="mailto:edreamleo&#37;&#52;&#48;gmail&#46;com">edreamleo<span>&#64;</span>gmail<span>&#46;</span>com</a>.</p></li>
</ul>
</section>
</section>
<section id="excel">
<h2><a class="toc-backref" href="#id44">Excel</a><a class="headerlink" href="#excel" title="Permalink to this heading">¶</a></h2>
<section id="how-can-i-show-leo-files-with-excel">
<h3><a class="toc-backref" href="#id45">How can I show Leo files with Excel?</a><a class="headerlink" href="#how-can-i-show-leo-files-with-excel" title="Permalink to this heading">¶</a></h3>
<p>Using Leo’s File-Export-Flatten Outline commands creates a MORE style outline which places all Leo body sections on the left margin. The <a class="reference external" href="glossary.html#headlines">headlines</a> are indented with tabs which Excel will read as a tab delimited format. Once inside Excel there are benefits.</p>
<ol class="arabic">
<li><p>The most obvious benefit inside Excel is that the body sections (Excel first column) can be selected easily and highlighted with a different font color. This makes the MORE format very readable. Save a copy of your sheet as HTML and now you have a web page with the body sections highlighted.</p></li>
<li><p>It is possible to hide columns in Excel. Hiding the first column leaves just the headlines showing.</p></li>
<li><p>Formulas based on searching for a string can do calculations in Excel. For example if a heading “Current Assets” appears on level 4 then the body formula:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">=</span><span class="n">INDEX</span><span class="p">(</span><span class="n">A</span><span class="p">:</span><span class="n">A</span><span class="p">,</span><span class="n">MATCH</span><span class="p">(</span><span class="s2">&quot;Current Assets&quot;</span><span class="p">,</span><span class="n">D</span><span class="p">:</span><span class="n">D</span><span class="p">,</span><span class="mi">0</span><span class="p">)</span><span class="o">+</span><span class="mi">1</span><span class="p">)</span>
</pre></div>
</div>
</li>
</ol>
<p>will retrieve it. The +1 after match looks down one row below the matched headline. The trick is to place all your headlines in quotes because Excel will see + “Current Assets” from the MORE outline. When Excel tries without the quotes it thinks it is a range name and displays a #N/A error instead of the headline. Also you must place a child <a class="reference external" href="glossary.html#node">node</a> below to get the + sign instead of a - sign which would give a MORE headline of -“Current assets” , also is an error.</p>
<p>I think there is some interesting possibility here because of the enforcement of Leo body text being always in the first column. The Leo outline provides additional reference to organizing the problem not typical of spreadsheet models. Beyond scripting in Python, Excel is good at doing interrelated calculations and detecting problems like circular references. In Excel Tools-Options-General is a setting for r1c1 format which then shows numbers instead of letters for column references. Using this would allow entries like this in the leo body:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">1000</span>
<span class="mi">3500</span>
<span class="o">=</span><span class="n">R</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span><span class="n">C</span><span class="o">+</span><span class="n">R</span><span class="p">[</span><span class="o">-</span><span class="mi">2</span><span class="p">]</span><span class="n">C</span>
</pre></div>
</div>
<p>In Excel you would see 4500 below those two numbers. This is completely independent of where the block of three cells exists on the sheet.</p>
</section>
</section>
<section id="files">
<h2><a class="toc-backref" href="#id46">Files</a><a class="headerlink" href="#files" title="Permalink to this heading">¶</a></h2>
<section id="can-file-trees-contain-material-not-in-the-external-file">
<h3><a class="toc-backref" href="#id47">Can &#64;file trees contain material not in the external file?</a><a class="headerlink" href="#can-file-trees-contain-material-not-in-the-external-file" title="Permalink to this heading">¶</a></h3>
<p>No. Everything in an &#64;file trees must be part of the external file: orphan and &#64;ignore nodes are invalid in &#64;file trees. This restriction should not be troublesome. For example, you can organize your outline like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">+</span> <span class="n">myClass</span>
<span class="o">..+</span> <span class="n">ignored</span> <span class="n">stuff</span>
<span class="o">..+</span> <span class="nd">@file</span> <span class="n">myClass</span>
</pre></div>
</div>
<p>(As usual, + denotes a headline.) So you simply create a new <a class="reference external" href="glossary.html#node">node</a>, called myClass, that holds your &#64;file trees and stuff you don’t want in the &#64;file trees.</p>
</section>
<section id="how-can-i-avoid-getting-long-lines-in-external-files">
<h3><a class="toc-backref" href="#id48">How can I avoid getting long lines in external files?</a><a class="headerlink" href="#how-can-i-avoid-getting-long-lines-in-external-files" title="Permalink to this heading">¶</a></h3>
<p><strong>Question</strong>: I must follow a coding standard when writing source code. It includes a maximum line length restriction. How can I know the length of a line when it gets written to the external file?</p>
<p><strong>Answer</strong>: If a node belongs to a external file hierarchy, its body might get indented when it is written to the external file. It happens when an &#64;others directive or a section name appears indented in a higher-level node body. While (<strong>line</strong>, <strong>col</strong>) in status area show the line and column containing the body text’s cursor, <strong>fcol</strong> shows the cursor coordinate relative to the external file, not to the current node. The relation <strong>fcol &gt;= col</strong> is always true.</p>
</section>
<section id="how-can-i-create-a-template-leo-file">
<h3><a class="toc-backref" href="#id49">How can I create a template .leo file?</a><a class="headerlink" href="#how-can-i-create-a-template-leo-file" title="Permalink to this heading">¶</a></h3>
<p><strong>Question</strong>: It would be nice if Leo could open empty files. I tend to be “document oriented” rather than “application oriented” in my thinking and prefer “create empty file at location -&gt; open it with program” to “start program -&gt; create new file -&gt; save it at location”.</p>
<p><strong>Answer</strong> by Paul Paterson: If you are on Windows 98/2000/XP then the procedure is as follows…</p>
<ol class="arabic simple">
<li><p>Start Leo</p></li>
<li><p>Click New</p></li>
<li><p>Click Save as…</p></li>
<li><p>Save the file as “c:\windows\shellnew\leofile.leo” (or c:\winnt for 2000/XP)</p></li>
<li><p>Open regedit “start…run…regedit”</p></li>
<li><p>Open HKEY_CLASSES_ROOT and find the “.leo” extension type</p></li>
<li><p>Go New … Key from the context menu</p></li>
<li><p>Call the new key ShellNew</p></li>
<li><p>Select the new key, right-click, choose New…String Value from the context menu</p></li>
<li><p>Call it FileName</p></li>
<li><p>Double-click on the string, and modify it to be the filename of the leofile.leo file you created, including the extension</p></li>
<li><p>Exit the registry editor and restart Windows Explorer (you may need to reboot on Windows 98)</p></li>
</ol>
<p>Now you should have a New:Leo File option in Explorer. This creates a duplicate of the file you saved. This can be useful because you could make a template Leo file containing some standard <a class="reference external" href="glossary.html#nodes">nodes</a> that you always have and then save this.</p>
</section>
<section id="how-can-i-create-javascript-comments">
<h3><a class="toc-backref" href="#id50">How can I create Javascript comments?</a><a class="headerlink" href="#how-can-i-create-javascript-comments" title="Permalink to this heading">¶</a></h3>
<p><strong>Question</strong>: I’m writing a Windows Script Component, which is an XML file with a CData section containing javascript. I can get the XML as I want it by using &#64;language html, but how can I get the tangling comments inside the CData section to be java-style comments rather than html ones?</p>
<p><strong>Answer</strong>: In &#64;file trees you use the &#64;delims directive to change comment delimiters. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@delims</span> <span class="o">/*</span> <span class="o">*/</span>
<span class="n">Javascript</span> <span class="n">stuff</span>
<span class="nd">@delims</span> <span class="o">&lt;--</span> <span class="o">--&gt;</span>
<span class="n">HTML</span> <span class="n">stuff</span>
</pre></div>
</div>
<p><strong>Important</strong>: Leo can not revert to previous delimiters automatically; you must change back to previous delimiters using another &#64;delims <a class="reference external" href="glossary.html#directive">directive</a>.</p>
</section>
<section id="how-can-i-disable-php-comments">
<h3><a class="toc-backref" href="#id51">How can I disable PHP comments?</a><a class="headerlink" href="#how-can-i-disable-php-comments" title="Permalink to this heading">¶</a></h3>
<p>By Zvi Boshernitzan: I was having trouble disabling ‘&lt;?php’ with comments (and couldn’t override the comment character for the start of the page). Finally, I found a solution that worked, using php’s heredoc string syntax:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>@first &lt;?php
@first $comment = &lt;&lt;&lt;EOD
EOD;

// php code goes here.
echo &quot;boogie&quot;;

$comment2 = &lt;&lt;&lt;EOD
@last EOD;
@last ?&gt;
</pre></div>
</div>
<p>or:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>@first &lt;?php
@first /*
*/

echo &quot;hi&quot;;

@delims /* */
@last ?&gt;
</pre></div>
</div>
</section>
<section id="how-can-i-open-special-leo-files-easily">
<h3><a class="toc-backref" href="#id52">How can I open special .leo files easily?</a><a class="headerlink" href="#how-can-i-open-special-leo-files-easily" title="Permalink to this heading">¶</a></h3>
<p>You can open files such as CheatSheet.leo, quickstart.leo, leoSettings.leo, myLeoSettings.leo and scripts.leo with commands starting with ‘leo-‘.</p>
<p>&lt;Alt-X&gt;leo-&lt;tab&gt; shows the complete list of commands:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">leo</span><span class="o">-</span><span class="n">cheat</span><span class="o">-</span><span class="n">sheet</span>
<span class="n">leo</span><span class="o">-</span><span class="n">dist</span><span class="o">-</span><span class="n">leo</span>
<span class="n">leo</span><span class="o">-</span><span class="n">docs</span><span class="o">-</span><span class="n">leo</span>
<span class="n">leo</span><span class="o">-</span><span class="n">plugins</span><span class="o">-</span><span class="n">leo</span>
<span class="n">leo</span><span class="o">-</span><span class="n">py</span><span class="o">-</span><span class="n">leo</span>
<span class="n">leo</span><span class="o">-</span><span class="n">quickstart</span><span class="o">-</span><span class="n">leo</span>
<span class="n">leo</span><span class="o">-</span><span class="n">scripts</span><span class="o">-</span><span class="n">leo</span>
<span class="n">leo</span><span class="o">-</span><span class="n">settings</span>
</pre></div>
</div>
</section>
<section id="how-can-i-specify-the-root-directory-of-a-thumb-drive">
<h3><a class="toc-backref" href="#id53">How can I specify the root directory of a thumb drive?</a><a class="headerlink" href="#how-can-i-specify-the-root-directory-of-a-thumb-drive" title="Permalink to this heading">¶</a></h3>
<p>Use the %~dp0 syntax.  Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%~</span><span class="n">dp0</span>\<span class="n">Python27</span>\<span class="n">python</span><span class="o">.</span><span class="n">exe</span> <span class="o">%~</span><span class="n">dp0</span>\<span class="n">Leo</span><span class="o">-</span><span class="n">editor</span>\<span class="n">launchLeo</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p><a class="reference external" href="http://ss64.com/nt/syntax-args.html">http://ss64.com/nt/syntax-args.html</a>
<a class="reference external" href="http://stackoverflow.com/questions/5034076/what-does-dp0-mean-and-how-does-it-work">http://stackoverflow.com/questions/5034076/what-does-dp0-mean-and-how-does-it-work</a></p>
<p>FYI, this FAQ entry fixes the following bug: <a class="reference external" href="https://bugs.launchpad.net/leo-editor/+bug/613153">https://bugs.launchpad.net/leo-editor/+bug/613153</a> unable to describe root directory on thumb drive</p>
</section>
<section id="how-can-i-use-leo-with-older-c-compilers">
<h3><a class="toc-backref" href="#id54">How can I use Leo with older C compilers</a><a class="headerlink" href="#how-can-i-use-leo-with-older-c-compilers" title="Permalink to this heading">¶</a></h3>
<p>By Rich Ries. Some older C compilers don’t understand the “//” comment symbol, so using &#64;language C won’t work. Moreover, the following does not always work either:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@comment</span> <span class="o">/*</span> <span class="o">*/</span>
</pre></div>
</div>
<p>This generates the following sentinel line:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">/*@</span><span class="nd">@comment</span> <span class="o">/*</span> <span class="o">*/*/</span>
</pre></div>
</div>
<p>in the output file, and not all C compilers allow nested comments, so the last */ generates an error. The solution is to use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">#if 0</span>
<span class="nd">@comment</span> <span class="o">/*</span> <span class="o">*/</span>
<span class="c1">#endif</span>
</pre></div>
</div>
<p>Leo is happy: it recognizes the &#64;comment <a class="reference external" href="glossary.html#directive">directive</a>. The C compiler is happy: the C preprocessor strips out the offending line before the C compiler gets it.</p>
</section>
<section id="how-can-i-use-leo-with-unsupported-languages">
<h3><a class="toc-backref" href="#id55">How can I use Leo with unsupported languages?</a><a class="headerlink" href="#how-can-i-use-leo-with-unsupported-languages" title="Permalink to this heading">¶</a></h3>
<p>The &#64;first <a class="reference external" href="glossary.html#directive">directive</a> is the key to output usable code in unsupported languages. For example, to use Leo with the Basic language, use the following:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>@first $IFDEF LEOHEADER
@delims &#39;
@c
$ENDIF
</pre></div>
</div>
<p>So this would enable a basic compiler to “jump” over the “true” Leo-header-lines. Like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$IFDEF LEOHEADER &lt;-conditional compilation directive
#@+leo-ver=4 &lt;-these lines not compiled
#@+node:@file QParser005.INC
#@@first
#@delims &#39;
&#39;@@c
$ENDIF &lt;-... Until here!
&lt;rest of derived code file ... &gt;
</pre></div>
</div>
<p>This changes the comment symbol the apostrophe, making comments parseable by a BASIC (or other language.)</p>
</section>
<section id="how-do-i-inhibit-sentinels-in-external-files">
<h3><a class="toc-backref" href="#id56">How do I inhibit sentinels in external files?</a><a class="headerlink" href="#how-do-i-inhibit-sentinels-in-external-files" title="Permalink to this heading">¶</a></h3>
<p>Use &#64;clean trees. Files derived from &#64;clean trees contain no <a class="reference external" href="glossary.html#sentinels">sentinels</a>. However, Leo can update &#64;clean trees from changes made to the corresponding external file.  The <a class="reference external" href="appendices.html#the-mulder-ream-update-algorithm">Mulder/Ream update algorithm</a> makes this magic happen.</p>
</section>
<section id="how-do-i-make-external-files-start-with-a-shebang-line">
<h3><a class="toc-backref" href="#id57">How do I make external files start with a shebang line?</a><a class="headerlink" href="#how-do-i-make-external-files-start-with-a-shebang-line" title="Permalink to this heading">¶</a></h3>
<p>Use the &#64;first <a class="reference external" href="glossary.html#directive">directive</a> in &#64;file or &#64;clean trees. The &#64;first directive puts lines at the very start of files derived from &#64;file. For example, the body text of &#64;file spam.py might be:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@first</span> <span class="c1">#! /usr/bin/env python</span>
</pre></div>
</div>
<p>The body text of &#64;file foo.pl might be:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@first</span> <span class="c1">#/usr/bin/perl</span>
</pre></div>
</div>
<p>&#64;first directives must be the <em>very first</em> lines of &#64;file nodes. More than one &#64;first directive may exist, like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@first</span> <span class="c1">#! /usr/bin/env python</span>
<span class="nd">@first</span> <span class="c1"># more comments.</span>
</pre></div>
</div>
</section>
<section id="how-do-i-prevent-leo-from-expanding-sections">
<h3><a class="toc-backref" href="#id58">How do I prevent Leo from expanding sections?</a><a class="headerlink" href="#how-do-i-prevent-leo-from-expanding-sections" title="Permalink to this heading">¶</a></h3>
<p>Use &#64;asis trees. Files derived from &#64;asis trees contain no sentinels. Leo creates the external file simply by writing all body text in outline order. Leo can’t update the outline unless the external file contains sentinels, so Leo does not update &#64;asis trees automatically when you change the external file in an external editor.</p>
</section>
<section id="why-can-t-i-use-ignore-directives-in-file-trees">
<h3><a class="toc-backref" href="#id59">Why can’t I use &#64;ignore directives in &#64;file trees?</a><a class="headerlink" href="#why-can-t-i-use-ignore-directives-in-file-trees" title="Permalink to this heading">¶</a></h3>
<p>&#64;ignore can only be used in the root node of &#64;file trees.  It tells Leo to ignore the tree.</p>
<p>The &#64;ignore directive can not be used elsewhere in &#64;file trees because of the way Leo recreates outlines from external files. This is an absolutely crucial restriction and will never go away. For a few more details, see <a class="reference external" href="appendices.html#leo-4-0-eliminating-error-recovery">Leo 4.0: Eliminating error ‘recovery’</a> in <a class="reference external" href="appendices.html#history-of-leo">History of Leo</a>.</p>
<p>There are several workaround, as shown in LeoPy.leo:</p>
<ul class="simple">
<li><p>keep notes in the outline outside of any external file.</p></li>
<li><p>Use &#64;all to gather notes in a external file, as in done in &#64;file leoProjects.txt.</p></li>
</ul>
</section>
</section>
<section id="id2">
<h2><a class="toc-backref" href="#id60">Git</a><a class="headerlink" href="#id2" title="Permalink to this heading">¶</a></h2>
<section id="how-can-i-use-git-to-check-leo-s-importers">
<h3><a class="toc-backref" href="#id61">How can I use git to check Leo’s importers?</a><a class="headerlink" href="#how-can-i-use-git-to-check-leo-s-importers" title="Permalink to this heading">¶</a></h3>
<p>When I study a program, I like to import it into Leo. I have several scripts that do this: some create &#64;auto nodes; others create &#64;file nodes. Whatever the method used, the import process has the potential to change many files. Usually, I just change &#64;auto and &#64;file to &#64;&#64;auto or &#64;&#64;file, so that any changes I make while studying the code won’t affect the originals.</p>
<p>But this “safety first” approach means that I can’t actually use Leo to insert tracing statements (or for any other changes.) Happily, there is a way to import “live” code into Leo safely:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Create</span> <span class="n">a</span> <span class="n">git</span> <span class="n">repository</span> <span class="k">for</span> <span class="n">the</span> <span class="n">code</span> <span class="n">before</span> <span class="n">importing</span> <span class="n">it</span>
</pre></div>
</div>
<p>The Aha is to create the repository <em>wherever the code is</em>, including,
say, python/Lib/site-packages.</p>
<ul class="simple">
<li><p>git diff ensures that import hasn’t significantly altered the code,</p></li>
</ul>
<p>This is exactly what I need:  I can make changes to important tools <em>safely</em> within Leo.</p>
</section>
<section id="how-can-i-use-leo-with-git">
<h3><a class="toc-backref" href="#id62">How can I use Leo with git?</a><a class="headerlink" href="#how-can-i-use-leo-with-git" title="Permalink to this heading">¶</a></h3>
<p>Imo, git rivals python as the greatest productivity tool ever devised for programmers.</p>
<p>My workflow on Ubuntu and Windows is essentially identical. Simple aliases (Ubuntu) and .bat files (Windows) support the following console commands:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">gs</span>  <span class="p">(</span><span class="n">expands</span> <span class="n">to</span> <span class="n">git</span> <span class="n">status</span><span class="p">)</span>
<span class="n">gd</span> <span class="p">(</span><span class="n">git</span> <span class="n">diff</span><span class="p">)</span>  <span class="n">Uses</span> <span class="n">an</span> <span class="n">external</span> <span class="n">diff</span> <span class="n">program</span><span class="p">,</span>
               <span class="n">but</span> <span class="n">I</span><span class="s1">&#39;m starting to prefer text diffs.</span>
<span class="n">ga</span> <span class="o">.</span> <span class="p">(</span><span class="n">git</span> <span class="n">add</span> <span class="o">.</span><span class="p">)</span>
<span class="n">ga</span> <span class="n">file</span> <span class="p">(</span><span class="n">git</span> <span class="n">add</span> <span class="n">file</span><span class="p">)</span>
<span class="n">gc</span> <span class="p">(</span><span class="n">git</span> <span class="n">commit</span><span class="p">:</span> <span class="n">configured</span> <span class="n">to</span> <span class="nb">open</span> <span class="n">Scite</span> <span class="n">to</span> <span class="n">create</span> <span class="n">a</span> <span class="n">commit</span> <span class="n">message</span><span class="p">)</span>
<span class="n">gc</span> <span class="o">-</span><span class="n">m</span> <span class="s2">&quot;a one-line commit message&quot;</span>
<span class="n">push</span> <span class="p">(</span><span class="n">git</span> <span class="n">push</span><span class="p">)</span>
</pre></div>
</div>
<p>I use gitk on both platforms to review commits.</p>
<p>And that’s about it. I use “git help” and “git help command” as needed.</p>
</section>
<section id="how-should-i-use-leo-with-git-etc">
<h3><a class="toc-backref" href="#id63">How should I use Leo with git, etc.?</a><a class="headerlink" href="#how-should-i-use-leo-with-git-etc" title="Permalink to this heading">¶</a></h3>
<p>Use &#64;clean or &#64;auto unless everyone in your work group uses Leo.  In that case, using &#64;file is best.  Use local copies of <a class="reference external" href="FAQ.html#what-is-a-reference-leo-file">reference .leo files</a> instead of the reference files themselves.</p>
</section>
<section id="what-is-a-reference-leo-file">
<h3><a class="toc-backref" href="#id64">What is a reference .leo file?</a><a class="headerlink" href="#what-is-a-reference-leo-file" title="Permalink to this heading">¶</a></h3>
<p><cite>leoeditor/leo/core</cite> contains a <strong>reference .leo file</strong>: <strong>LeoPyRef.leo</strong>.</p>
<p>This file should change only when adding new external files to Leo.</p>
<p>Developers should use a local copy of LeoPyRef.leo (conventionally called
<strong>leoPy.leo</strong>) for their own work.</p>
</section>
<section id="why-do-files-sometimes-change-when-switching-branches">
<h3><a class="toc-backref" href="#id65">Why do files sometimes change when switching branches?</a><a class="headerlink" href="#why-do-files-sometimes-change-when-switching-branches" title="Permalink to this heading">¶</a></h3>
<p>Private copies of LeoPyRef.leo, that is, leoPy.leo, are “global”.  That is, they persist unchanged when switching branches.  In effect, they act like (sometimes) unwanted caches.</p>
<p>If you change the <em>structure</em> of &#64;file nodes in leoPy.leo in one branch, such changes will “propagate” to other branches, even though the contents of each node has remained the same.</p>
<p>You can see such changes clearly using leo –diff.</p>
<p>In short, don’t make unnecessary structural changes in leoPy.leo when in branches other than master.</p>
</section>
</section>
<section id="graphics">
<h2><a class="toc-backref" href="#id66">Graphics</a><a class="headerlink" href="#graphics" title="Permalink to this heading">¶</a></h2>
<section id="how-can-i-display-graphics-in-leo">
<h3><a class="toc-backref" href="#id67">How can I display graphics in Leo?</a><a class="headerlink" href="#how-can-i-display-graphics-in-leo" title="Permalink to this heading">¶</a></h3>
<p>One way is to link directly to the media file from a Leo <a class="reference external" href="glossary.html#node">node</a> (with &#64;url) and write a script button to wrap all URL-nodes under the current <a class="reference external" href="glossary.html#node">node</a> in a single HTML page. Then, you can view your media in two ways:</p>
<ul class="simple">
<li><p>Individually. You can directly click on the &#64;url link to display the media in the browser (assuming you have your MIME/filetype associations set up correctly for your browser).</p></li>
<li><p>In a group. You can click on a script button (you have to code this yourself, very simple) which should collect all &#64;url <a class="reference external" href="glossary.html#nodes">nodes</a> under the current <a class="reference external" href="glossary.html#node">node</a> and dynamically generate a HTML page displaying either links to or embedded versions of the media (using the HTML trick described above to invoke the browser). This way, you can create collections of &#64;url nodes under a single <a class="reference external" href="glossary.html#node">node</a> (like a bookmark folder), and press a single button to view the &#64;url collection as a single entity in the browser (with all browser capabilities like displaying the media).</p></li>
</ul>
<p>You could probably generalize this idea of “collect all &#64;url nodes under current <a class="reference external" href="glossary.html#node">node</a> and display as HTML in browser” into a general-purpose plugin. However, the plugin would have to be somewhat smart in mapping a link to its corresponding HTML code (e.g. an image link gets mapped to an &lt;img&gt; HTML tag, a link to a Flash file gets mapped to an &lt;embed&gt; tag, etc).</p>
</section>
<section id="how-can-i-make-a-screencast">
<h3><a class="toc-backref" href="#id68">How can I make a screencast?</a><a class="headerlink" href="#how-can-i-make-a-screencast" title="Permalink to this heading">¶</a></h3>
<p>Making screencasts is a lot easier than you probably think. Here are some tips to get you started quickly.</p>
<section id="use-a-script-to-open-your-app">
<h4><a class="toc-backref" href="#id69">Use a script to open your app</a><a class="headerlink" href="#use-a-script-to-open-your-app" title="Permalink to this heading">¶</a></h4>
<p>The primary purpose of this script is to open your app at a fixed, unchanging size. This is surprisingly important:</p>
<ul class="simple">
<li><p>It ensures that the window will always render to pixels in the same way.</p></li>
<li><p>It makes it easier to splice in new video to an existing video.</p></li>
<li><p>It makes it easier to plan your video to ensure everything will appear as you expect.</p></li>
<li><p>It provides continuity when making a series of videos.</p></li>
</ul>
<p>Here is a script that I use when making Leo’s screencasts:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>python launchLeo.py --gui=qttabs
--window-size=682x1264 &lt;list of .leo files&gt; %*​
</pre></div>
</div>
<p>This <em>particular</em> –window-size causes Camtasia to create a window whose actual size is 720x1280, the nominal 720p resolution. It may prevent text blur. Or not. I do know that Leo’s screencasts look great at 720p.</p>
</section>
<section id="debug-your-workflow-with-short-videos">
<h4><a class="toc-backref" href="#id70">Debug your workflow with short videos</a><a class="headerlink" href="#debug-your-workflow-with-short-videos" title="Permalink to this heading">¶</a></h4>
<p>Make sure that you can actually upload <em>excellent quality</em> videos before doing anything else. This step is crucial. If you skip this step, all of your initial recording an post-production work could be utterly wasted.</p>
<p>Use <em>short</em> (10-second) test videos at this step. Their primary purpose verify that you can can get to the <em>end</em> of the production process successfully. You <em>are</em> going to make lots of mistakes here: using short videos helps you make these mistakes quickly.</p>
<p>Don’t even <em>think</em> about making longer videos until the answers to all the following questions are clearly “yes”:</p>
<ul class="simple">
<li><p>Is your camera working?</p></li>
<li><p>Is your microphone working?</p></li>
<li><p>Do you know how to record your voice and screen?</p></li>
<li><p>Can you log into YouTube or screencast.com?</p></li>
<li><p>Can you upload to YouTube or screencast.com?</p></li>
<li><p>Is the sound in your <em>uploaded</em> video great?</p></li>
<li><p>Do the pixels in your <em>uploaded</em> look great?</p></li>
</ul>
<p>This last item is particularly important. Just because pixels look good in your video editor is no guarantee that they will look good when uploaded.</p>
<p>You are ready to try your first “real” take <em>only</em> when you can upload a video that looks and sounds great.</p>
</section>
<section id="emulate-the-screencast-com-tutorials">
<h4><a class="toc-backref" href="#id71">Emulate the screencast.com tutorials</a><a class="headerlink" href="#emulate-the-screencast-com-tutorials" title="Permalink to this heading">¶</a></h4>
<p>Before rushing right out and making your first video, I recommend watching the tutorial screencasts at screencast.com: <a class="reference external" href="http://www.techsmith.com/tutorial-camtasia-8.html">http://www.techsmith.com/tutorial-camtasia-8.html</a></p>
<p>Watch the tutorials to see how the presentations themselves are organized. Watch them until it feels natural to emulate their style.</p>
<p>If you will be using Camtasia, you will also want to watch the tutorials to learn how Camtasia works.</p>
</section>
<section id="record-your-first-real-take">
<h4><a class="toc-backref" href="#id72">Record your first real take</a><a class="headerlink" href="#record-your-first-real-take" title="Permalink to this heading">¶</a></h4>
<p>Now it’s time to go beyond test videos. Even now, though, I recommend keeping your first efforts short: one minute or so. Again, this saves time. You’ll ending up throwing away two or three anyway ;-)</p>
<p>Bring up your app using you demo script and run through your presentation.</p>
<p>Here’s the <strong>most important tip</strong>: As you narrate your video, audio flubs are inevitable, but they don’t matter at all <em>provided</em> that you <em>realize</em> that you have just flubbed a word or phrase.</p>
<p>When you flub a line, don’t panic! Just <em>pause</em>, regroup, and repeat the phrase until you get it right. <em>Pausing is essential</em>: it simplifies inserting and deleting sound bites during post production.</p>
<p>You’ll relax once you realize that flubs don’t matter and that pausing makes post-production easier. Once you relax, getting a good take will suddenly become easier.</p>
<p>Correcting flubs <em>as soon as they happen</em> is absolutely essential. Don’t even <em>think</em> about fixing audio flubs in post-production. It simply can’t be done. Instead of spending 20 minutes trying (and failing) to correct a flub in post production, it is much faster and better to take 20 seconds during your take to correct the flub.</p>
<p>Similar remarks apply to video, but in my experience it’s much easier to get the video right. If you do flub the video, it will be much easier if you just do a complete retake. With Camtasia, you can separate the audio and video tracks, but usually that won’t work, especially if there is audio of key clicks.</p>
<p>By retaking audio flubs as they happen, I find it easy to work without a script. It feels more natural to me than reading a script. YMMV. When I get stuck, I just pause. Or just start over. Otoh, it wouldn’t be that hard to read a script. Just <em>pause</em> before and after each phrase. Never rush your audio!</p>
<p>In short, the key Aha is: insert (audio) pauses <em>everywhere</em> as needed. It’s easy to edit them out. It’s virtually impossible to edit in the middle of words, even with the world’s best audio editor.</p>
</section>
<section id="edit-your-raw-take">
<h4><a class="toc-backref" href="#id73">Edit your raw take</a><a class="headerlink" href="#edit-your-raw-take" title="Permalink to this heading">¶</a></h4>
<p>Post production should be easy provided that you have corrected all audio flubs as they happen. This keeps the audio and video in sync. Just edit out flubs and reduce overly-long pauses.</p>
<p>I won’t discuss production details here because they depend on the editor you are using.</p>
<p>Do a new take if you don’t have clean audio. Depending on the complexity of your video, it may be possible to splice a partial take in the middle or end of your video. Similarly, it may be possible to splice in a new take to add material you didn’t cover in your first take.</p>
<p>One final word of advice. When editing your video, settle for “good enough”. Perfectionism is not your friend.</p>
</section>
<section id="summary">
<h4><a class="toc-backref" href="#id74">Summary</a><a class="headerlink" href="#summary" title="Permalink to this heading">¶</a></h4>
<p>Making a screencast is a lot easier than you think :-)</p>
<ul>
<li><p>Create a script that will open your app at a fixed, optimal, size.</p></li>
<li><p>Emulate the style and form of screencast.com tutorials.</p></li>
<li><p>Verify the <em>entire</em> production process with short test videos.</p>
<p>Before making longer videos, make <em>sure</em> that the test videos look and sound great <em>when they have been uploaded</em>.</p>
</li>
<li><p>When doing a take, flubs don’t matter, <em>provided</em> you correct them <em>during the take</em>.  Use pauses.  Make haste slowly!</p></li>
<li><p>Splice in new takes during post-production to fix flubs and add new material.</p></li>
</ul>
</section>
<section id="additional-tips">
<h4><a class="toc-backref" href="#id75">Additional tips</a><a class="headerlink" href="#additional-tips" title="Permalink to this heading">¶</a></h4>
<p>Here are some more tips I’ve learned from experience:</p>
<ol class="arabic simple">
<li><p>Redo audio tests and video tests every time you start a new session. It’s amazing how hum can creep into recordings.</p></li>
<li><p>The most important step in post production is to get the pacing so it feels right. Beware of editing out pauses. Make sure you give your viewers time to see what you are doing, and to see what you have done.</p></li>
<li><p>Don’t waste time on callouts or captions until the audio and video work together at a relaxed pace. It’s almost as hard to correct pacing mistakes as it is to correct audio flubs.</p></li>
</ol>
</section>
<section id="tips-for-improving-audio">
<h4><a class="toc-backref" href="#id76">Tips for improving audio</a><a class="headerlink" href="#tips-for-improving-audio" title="Permalink to this heading">¶</a></h4>
<ol class="arabic simple">
<li><p>Enable volume leveling and noise removal in Camtasia. This tip, all by itself, makes a big difference.</p></li>
<li><p>Use a better microphone, preferably one with about a 1-inch diaphragm. This is the kind of microphone that Andrew Price uses. The Audio-technica AT2020 USB is relatively inexpensive.</p></li>
<li><p>Use “pop filter” with the microphone. This is a cloth or (better) a metal screen that is placed in front of the microphone. It smooths the sound.</p></li>
<li><p>Adjust the sound level for maximum volume without distortion: With the microphone about a foot from your mouth, turn the volume as loud as possible, then turn down until no red is visible in the meter.</p></li>
</ol>
</section>
</section>
</section>
<section id="importing-files">
<h2><a class="toc-backref" href="#id77">Importing files</a><a class="headerlink" href="#importing-files" title="Permalink to this heading">¶</a></h2>
<section id="how-can-i-import-many-files-at-once">
<h3><a class="toc-backref" href="#id78">How can I import many files at once?</a><a class="headerlink" href="#how-can-i-import-many-files-at-once" title="Permalink to this heading">¶</a></h3>
<p>The Import Files dialog allows you to select multiple files provided you are running Python 2.3 or above. There is also an importFiles script in LeoPy.leo.  You can use that script as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">leo.core.leoImport</span> <span class="k">as</span> <span class="nn">leoImport</span>
<span class="n">leoImport</span><span class="o">.</span><span class="n">importFiles</span><span class="p">(</span><span class="n">aDirectory</span><span class="p">,</span> <span class="s2">&quot;.py&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>This will import all .py files from aDirectory, which should be a full path to a particular directory. You could use “.c” to import all .c files, etc.</p>
</section>
</section>
<section id="latex">
<h2><a class="toc-backref" href="#id79">LaTeX</a><a class="headerlink" href="#latex" title="Permalink to this heading">¶</a></h2>
<section id="how-can-i-produce-pdf-output-from-latex-input">
<h3><a class="toc-backref" href="#id80">How can I produce PDF output from LaTex input?</a><a class="headerlink" href="#how-can-i-produce-pdf-output-from-latex-input" title="Permalink to this heading">¶</a></h3>
<p>From this <a class="reference external" href="https://groups.google.com/d/msg/leo-editor/83avo6mgHXY/nIKOpztyAAAJ">long discussion</a> on leo-editor:</p>
<p>From Rob Keeney:</p>
<p><strong>Typical Use case</strong></p>
<p>I teach a variety of classes in a business environment and need handouts,
teaching aids, worksheets and training manuals that are specifically
customized for each client. These documents are easier to manage, print and
protect using standard PDFs.</p>
<p><strong>Workflow Overview</strong></p>
<ul class="simple">
<li><p>Document content comes from a primary resource directory arranged by
topic (not client specific).</p></li>
<li><p>I have a Resources.leo file that helps me keep that directory organized.</p></li>
<li><p>All of the content files are written in LaTex (I use a .txi file
extension of my own invention to indicate the file is an ‘input’ file
only, not the main output file which uses .tex).</p></li>
<li><p>I have a Client.leo file for each client in their own directory to
organize work specific to each client.</p></li>
<li><p>For each document needed for a client project, I create a Document.tex
file from a standard template and change the document properties as
needed for the specific client, project and document.</p></li>
<li><p>The Document.tex file acts as the presentation ‘shell’ for the document
and I simply add input{”ResourcePath Content.txi”} after the
begin{document} statement (ResourcePath is a shortcut command to the
location of the content resource). This shell determines such things as
the document title, document type, client name, header/footer information
and revision date.</p></li>
<li><p>Since I work primarily in Windows, I use TeXNicCenter to process (typeset) the Document.tex file to create PDF output. (I do not use TeXNicCenter for editing, only file processing).</p></li>
</ul>
<p><strong>Workflow Notes and Shortcuts</strong></p>
<ul class="simple">
<li><p>Years ago, I discovered the incredible exam class for LaTex and now
use it almost exclusively. It makes it much easier to create student
and teacher versions of the same content (for example, handouts for
students and training manual with speaking notes for the teacher).</p></li>
<li><p>I use &#64;outline-data tree-abbreviations in Leo to create each new
Document.tex file from a template with variables (very cool!)</p></li>
<li><p>I created many &#64;data abbreviations in Leo to speed up typing of standard
LaTex structures (would be happy to share them if anyone is interested).</p></li>
<li><p>All document content stays in the Resources directory and only ‘shell’
documents are in the client directories.</p></li>
<li><p>These shell documents allow for client-specific information to be added
to the headers, footers and in some cases as variables inside the content
area itself (using theClient variable that I define).</p></li>
</ul>
<p><strong>Software Needed</strong></p>
<ul class="simple">
<li><p>Leo, and its dependencies.</p></li>
<li><p>MiKTex for the LaTex distribution and package management (I have it set
to auto-update as needed).</p></li>
<li><p>TeXNicCenter for processing (typesetting) to PDF output.</p></li>
</ul>
<p><strong>Example Leo file</strong></p>
<p>See this <a class="reference external" href="https://github.com/leo-editor/snippets/tree/master/examples/workflow/latex-pdf">example Leo file</a>.</p>
<p><strong>Questions</strong></p>
<p>Q: Can you control TexNicCenter from Leo - or do you process the file and preview process manually?</p>
<p>A: No, I run processing (typesetting) in TeXNicCenter manually. Typically,
I create a blank project file and open however many files required for that
project. That way it’s easier to clean up the extra files created during
the process steps. HTH. There might be a way to invoke the LaTex commands
through Leo, but that’s way above my pay grade.</p>
<p>From Arjan Mossel:</p>
<p>I’m using Leo to organize sections like chapter, section and subsection.
Since I’m just writing latex in Leo, I need to keep track of the right
hierarchies, so I can’t freely move nodes around in the hierarchy or I end
up with subsection at the same level as section, etc. It would be great
to be able to let Leo handle this.</p>
<dl class="simple">
<dt>MyProject</dt><dd><ul class="simple">
<li><p>&#64;clean myproject/myproject.tex</p></li>
<li><p>&#64;clean myproject/references.bib</p></li>
<li><p>Compile myproject.tex</p></li>
</ul>
</dd>
</dl>
<p>The compile node has something like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">os</span>
<span class="kn">import</span> <span class="nn">subprocess</span>
<span class="kn">import</span> <span class="nn">sys</span>

<span class="n">repository_dir</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">abspath</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">curdir</span><span class="p">)</span>

<span class="c1"># The system commands should be run from the folder containing the tex/cls/clo/bib files.</span>
<span class="n">working_dir</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">repository_dir</span><span class="p">,</span> <span class="s1">&#39;myproject&#39;</span><span class="p">)</span>
<span class="n">os</span><span class="o">.</span><span class="n">chdir</span><span class="p">(</span><span class="n">working_dir</span><span class="p">)</span>

<span class="c1"># The commands to run.</span>
<span class="n">run_xelatex</span> <span class="o">=</span> <span class="s1">&#39;xelatex &#39;</span> <span class="o">+</span> <span class="n">working_dir</span> <span class="o">+</span> <span class="n">os</span><span class="o">.</span><span class="n">sep</span> <span class="o">+</span> <span class="s1">&#39;myproject.tex&#39;</span>
<span class="n">run_bibtex</span> <span class="o">=</span>  <span class="s1">&#39;bibtex &#39;</span> <span class="o">+</span> <span class="n">working_dir</span> <span class="o">+</span> <span class="n">os</span><span class="o">.</span><span class="n">sep</span> <span class="o">+</span> <span class="s1">&#39;myproject&#39;</span>

<span class="n">g</span><span class="o">.</span><span class="n">es</span><span class="p">(</span><span class="s1">&#39;Running XeLaTeX and BibTeX&#39;</span><span class="p">)</span>
<span class="c1"># os.system starts a new subshell</span>
<span class="c1"># @todo: is it possible to run the below commands in one subshell consecutively?</span>
<span class="n">os</span><span class="o">.</span><span class="n">system</span><span class="p">(</span><span class="n">run_xelatex</span><span class="p">)</span>
<span class="n">os</span><span class="o">.</span><span class="n">system</span><span class="p">(</span><span class="n">run_bibtex</span><span class="p">)</span>
<span class="n">os</span><span class="o">.</span><span class="n">system</span><span class="p">(</span><span class="n">run_xelatex</span><span class="p">)</span>

<span class="c1"># Platform-independent file opening</span>
<span class="k">def</span> <span class="nf">open_file</span><span class="p">(</span><span class="n">filename</span><span class="p">):</span>
    <span class="k">if</span> <span class="n">sys</span><span class="o">.</span><span class="n">platform</span> <span class="o">==</span> <span class="s2">&quot;win32&quot;</span><span class="p">:</span>
        <span class="n">os</span><span class="o">.</span><span class="n">startfile</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="n">opener</span> <span class="o">=</span><span class="s2">&quot;xdg-open&quot;</span>
        <span class="n">subprocess</span><span class="o">.</span><span class="n">call</span><span class="p">([</span><span class="n">opener</span><span class="p">,</span> <span class="n">filename</span><span class="p">])</span>

<span class="n">open_file</span><span class="p">(</span><span class="s1">&#39;myproject.pdf&#39;</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="how-can-i-use-bibtex-citations-from-leo">
<h3><a class="toc-backref" href="#id81">How can I use BibTeX citations from Leo?</a><a class="headerlink" href="#how-can-i-use-bibtex-citations-from-leo" title="Permalink to this heading">¶</a></h3>
<p>When using LaTeX and BibTeX, I would like to use inside of Leo a kind of LaTeX-inline-markup, that after generation of the RsT file through Sphinx as well as after running of “make latex”, generate a LaTeX file containing the citation call of the form cite{CITBook001} as described in a file *.bib. Is there a way to have Leo/Sphinx/RsT generate the inline raw latex syntax?</p>
<p>Use the docutils <a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#raw-data-pass-through">raw-data</a> syntax. Examples:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">role</span><span class="p">::</span> <span class="n">raw</span><span class="o">-</span><span class="n">role</span><span class="p">(</span><span class="n">raw</span><span class="p">)</span>
  <span class="p">:</span><span class="nb">format</span><span class="p">:</span> <span class="n">html</span> <span class="n">latex</span>
<span class="o">..</span> <span class="n">raw</span><span class="p">::</span> <span class="n">latex</span>
  \<span class="n">bibliographystyle</span><span class="p">{</span><span class="n">acm</span><span class="p">}</span>
  \<span class="n">bibliography</span><span class="p">{</span><span class="n">myBibliography</span><span class="p">}</span>
</pre></div>
</div>
<p>For more details, see <a class="reference external" href="http://groups.google.com/group/leo-editor/browse_thread/thread/d36d76174dcd6786/9c2a298049f4f01c">this posting about BibTeX citations</a>.</p>
</section>
</section>
<section id="markdown-sphinx">
<h2><a class="toc-backref" href="#id82">Markdown &amp; Sphinx</a><a class="headerlink" href="#markdown-sphinx" title="Permalink to this heading">¶</a></h2>
<section id="how-can-i-create-markdown-files">
<h3><a class="toc-backref" href="#id83">How can I create markdown files?</a><a class="headerlink" href="#how-can-i-create-markdown-files" title="Permalink to this heading">¶</a></h3>
<p>Create your markdown files with &#64;auto-md myfile.md.</p>
<p>This automatically converts headlines to section headings.</p>
<p>Optional: change &#64;language md to &#64;language rest.
At present, syntax coloring for markdown is feeble.</p>
</section>
<section id="how-can-i-create-a-markdown-table-of-contents">
<h3><a class="toc-backref" href="#id84">How can I create a markdown table of contents?</a><a class="headerlink" href="#how-can-i-create-a-markdown-table-of-contents" title="Permalink to this heading">¶</a></h3>
<p>The &#64;button make-md-toc script in LeoDocs.leo writes a TOC to the console log.</p>
<p>Just select the &#64;auto-md node and execute the script.</p>
</section>
<section id="how-can-i-use-markdown-with-sphinx">
<h3><a class="toc-backref" href="#id85">How can I use Markdown with Sphinx?</a><a class="headerlink" href="#how-can-i-use-markdown-with-sphinx" title="Permalink to this heading">¶</a></h3>
<p>An <a class="reference external" href="https://github.com/leo-editor/leo-editor/issues/333">open issue</a> discusses various possibilities.</p>
</section>
</section>
<section id="scripting-testing">
<h2><a class="toc-backref" href="#id86">Scripting &amp; Testing</a><a class="headerlink" href="#scripting-testing" title="Permalink to this heading">¶</a></h2>
<section id="how-can-i-create-buttons-with-dropdown-menus">
<h3><a class="toc-backref" href="#id87">How can I create buttons with dropdown menus?</a><a class="headerlink" href="#how-can-i-create-buttons-with-dropdown-menus" title="Permalink to this heading">¶</a></h3>
<p>The code that handles the rclick menu is in the QtIconBarClass class in qt_frame.py.</p>
<p>Show that the  top-level button contains structure, do this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>@string mod_scripting_subtext = ▾
</pre></div>
</div>
<p>An alternative: ▼ U=25BC: Black Down-Pointing Triangle.</p>
<p>It’s reasonable to have the top-level button just be a placeholder for subsidiary &#64;rclick nodes. To do that without getting a warning when clicking the top-level button, set its script to “empty string”.</p>
</section>
<section id="how-can-i-make-commonly-used-scripts-widely-accessible">
<h3><a class="toc-backref" href="#id88">How can I make commonly-used scripts widely accessible?</a><a class="headerlink" href="#how-can-i-make-commonly-used-scripts-widely-accessible" title="Permalink to this heading">¶</a></h3>
<p>Put &#64;command nodes as children of an &#64;commands node in myLeoSettings.leo. This makes the &#64;command nodes available to all opened .leo files.</p>
<p>Using &#64;command rather than &#64;button means that there is never any need to disable scripts. There is no need for &#64;button. To see the list of your &#64;command nodes, type:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&lt;</span><span class="n">alt</span><span class="o">-</span><span class="n">x</span><span class="o">&gt;</span><span class="nd">@c</span><span class="o">&lt;</span><span class="n">tab</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>Similarly to see the list of your &#64;button nodes, type:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&lt;</span><span class="n">alt</span><span class="o">-</span><span class="n">x</span><span class="o">&gt;</span><span class="nd">@b</span><span class="o">&lt;</span><span class="n">tab</span><span class="o">&gt;</span>
</pre></div>
</div>
</section>
<section id="how-can-i-organize-large-docstrings">
<h3><a class="toc-backref" href="#id89">How can I organize large docstrings?</a><a class="headerlink" href="#how-can-i-organize-large-docstrings" title="Permalink to this heading">¶</a></h3>
<p>Start your file with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="sd">&#39;&#39;&#39;</span>
<span class="sd">&lt;&lt; docstring &gt;&gt;</span>
<span class="sd">&#39;&#39;&#39;</span>
</pre></div>
</div>
<p>The &lt;&lt; docstring &gt;&gt; section can just contain:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@language</span> <span class="n">rest</span> <span class="c1"># or md</span>
<span class="nd">@wrap</span>
<span class="nd">@others</span>
</pre></div>
</div>
<p>This allows the “interior” of the docstring to be colored using rST (or markdown).
The children of the &lt;&lt; docstring &gt;&gt; node form the actual docstring. No section names are required!</p>
<p>This pattern organizes large docstrings in a Leonine way. The only drawback is that the actual external file contains sentinel lines separating the parts of the docstring. In practice, it’s no big deal, especially if each child starts with a blank line.</p>
</section>
<section id="how-can-i-run-code-in-an-external-process">
<h3><a class="toc-backref" href="#id90">How can I run code in an external process?</a><a class="headerlink" href="#how-can-i-run-code-in-an-external-process" title="Permalink to this heading">¶</a></h3>
<p>g.execute_shell_commands executes one or more commands in a separate process using subprocess.popen. Commands <em>not</em> preceded by ‘&amp;’ run to completion before the next command is run.
See the scripting miscellany for more details.</p>
</section>
<section id="how-can-i-run-scripts-in-languages-other-than-python">
<h3><a class="toc-backref" href="#id91">How can I run scripts in languages other than python?</a><a class="headerlink" href="#how-can-i-run-scripts-in-languages-other-than-python" title="Permalink to this heading">¶</a></h3>
<p>The execute-general-script command invokes an external language processor on an <strong>script file</strong> as follows:</p>
<ul class="simple">
<li><p>If c.p is any kind of &#64;&lt;file&gt; node, the script file is the corresponding external file.
Otherwise, the script file is a temp file.</p></li>
<li><p>The <cite>&#64;data exec-script-commands</cite> setting tells how to invoke the appropriate language processor.
See the setting for more details.</p></li>
<li><p>The <cite>&#64;data exec-script-patterns</cite> settings describes error messages so that Leo can create
clickable links to errors.  See the setting for more details.</p></li>
<li><p>This command is a thin wrapper around the c.general_script_helper method.
Scripts can call this method directly if desired.</p></li>
</ul>
</section>
<section id="how-can-i-run-pylint-outside-of-leo">
<h3><a class="toc-backref" href="#id92">How can I run pylint outside of Leo?</a><a class="headerlink" href="#how-can-i-run-pylint-outside-of-leo" title="Permalink to this heading">¶</a></h3>
<p>Leo’s pylint command hangs Leo while it is running. The top-level leo-editor folder contains pylint-leo.py and pylint-leo-rc.txt. To run pylint outside of Leo, create a .bat or .sh file to run leo-editor/pylint-leo.py. On Windows, I use this pylint.bat file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python2</span> <span class="n">c</span><span class="p">:</span>\<span class="n">leo</span><span class="o">.</span><span class="n">repo</span>\<span class="n">leo</span><span class="o">-</span><span class="n">editor</span>\<span class="n">pylint</span><span class="o">-</span><span class="n">leo</span><span class="o">.</span><span class="n">py</span> <span class="o">^</span>
<span class="n">rc</span><span class="o">=</span><span class="n">c</span><span class="p">:</span>\<span class="n">leo</span><span class="o">.</span><span class="n">repo</span>\<span class="n">leo</span><span class="o">-</span><span class="n">editor</span>\<span class="n">leo</span>\<span class="n">test</span>\<span class="n">pylint</span><span class="o">-</span><span class="n">leo</span><span class="o">-</span><span class="n">rc</span><span class="o">.</span><span class="n">txt</span> <span class="o">%*</span>
</pre></div>
</div>
<p>The -h option produces this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Usage</span><span class="p">:</span> <span class="n">pylint</span><span class="o">-</span><span class="n">leo</span><span class="o">.</span><span class="n">py</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span>

<span class="n">Options</span><span class="p">:</span>
  <span class="o">-</span><span class="n">h</span><span class="p">,</span> <span class="o">--</span><span class="n">help</span>   <span class="n">show</span> <span class="n">this</span> <span class="n">help</span> <span class="n">message</span> <span class="ow">and</span> <span class="n">exit</span>
  <span class="o">-</span><span class="n">a</span>           <span class="nb">all</span>
  <span class="o">-</span><span class="n">c</span>           <span class="n">core</span>
  <span class="o">-</span><span class="n">e</span>           <span class="n">external</span>
  <span class="o">-</span><span class="n">f</span> <span class="n">FILENAME</span>  <span class="n">filename</span><span class="p">,</span> <span class="n">relative</span> <span class="n">to</span> <span class="n">leo</span> <span class="n">folder</span>
  <span class="o">-</span><span class="n">g</span>           <span class="n">gui</span> <span class="n">plugins</span>
  <span class="o">-</span><span class="n">m</span>           <span class="n">modes</span>
  <span class="o">-</span><span class="n">p</span>           <span class="n">plugins</span>
  <span class="o">-</span><span class="n">s</span>           <span class="n">silent</span>
  <span class="o">-</span><span class="n">u</span>           <span class="n">user</span> <span class="n">commands</span>
  <span class="o">-</span><span class="n">v</span>           <span class="n">report</span> <span class="n">pylint</span> <span class="n">version</span>
</pre></div>
</div>
<p>My typical usage is pylint -a -s</p>
</section>
<section id="how-can-i-test-settings-easily">
<h3><a class="toc-backref" href="#id93">How can I test settings easily?</a><a class="headerlink" href="#how-can-i-test-settings-easily" title="Permalink to this heading">¶</a></h3>
<p>Use .leo files to test settings rather than to contain data. These files would typically contain just an &#64;settings tree, and one or two nodes illustrating their effect. Opening such files limits the effects of experimental/non-standard/risky settings. This is a great tip to know.</p>
<p>For example, the files leo10pt.leo, leo12pt.leo, leo14-12pt.leo and leo14pt.leo in the leo/config folder make it easy to compare different font settings.</p>
<p>As another example, when starting the vim-mode project I created a .leo file containing &#64;bool vim-mode = True. By opening this file I test vim mode without interfering with my normal work flow.</p>
</section>
<section id="how-can-i-use-leo-in-virtualenv">
<h3><a class="toc-backref" href="#id94">How can I use Leo in virtualenv?</a><a class="headerlink" href="#how-can-i-use-leo-in-virtualenv" title="Permalink to this heading">¶</a></h3>
<p><a class="reference external" href="https://groups.google.com/d/msg/leo-editor/LePOMe_ckeg/_UasKCKP6NMJ">https://groups.google.com/d/msg/leo-editor/LePOMe_ckeg/_UasKCKP6NMJ</a></p>
<p>Some time ago there were a discussion about Leo in virtualenv.</p>
<p>Now I could test it in Python3, PyQt5 on Kubuntu:</p>
<p>Here are the steps (I worked in a folder with write permission ‘/leo’):</p>
<ol class="arabic simple">
<li><p>Install PyQt5 in the system:</p></li>
</ol>
<p>sudo aptitude install python3-pyqt5</p>
<ol class="arabic simple" start="2">
<li><p>Create the virtual environment with the ‘–system-site-packages’ switch and without pip (I’ve found this the only way, which worked):</p></li>
</ol>
<p>pyvenv-3.4 –system-site-packages –without-pip py3-pyqt5</p>
<ol class="arabic simple" start="3">
<li><p>Install setuptools and pip into the created environment:</p></li>
</ol>
<p>wget –no-check-certificate <a class="reference external" href="https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py">https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py</a> -O ez_setup.py</p>
<p>py3-pyqt5/bin/python ez_setup.py –insecure</p>
<p>wget –no-check-certificate <a class="reference external" href="https://pypi.python.org/packages/source/p/pip/pip-6.2.tar.gz#md5=2332e6f97e75ded3bddde0ced01dbda3">https://pypi.python.org/packages/source/p/pip/pip-6.2.tar.gz#md5=2332e6f97e75ded3bddde0ced01dbda3</a></p>
<p>tar xzvf pip-6.2.tar.gz</p>
<p>cd pip-6.2</p>
<p>../py3-pyqt5/bin/python setup.py install</p>
<p>cd ..</p>
<p>Now you can install what you want in the created environment, without affecting the system.</p>
<p>py3-pyqt5/bin/pip install Sphinx</p>
<ol class="arabic simple" start="4">
<li><p>From the leo-editor source folder launch Leo with the new interpreter:</p></li>
</ol>
<p>In my case:</p>
<p>/leo/py3-pyqt5/bin/python launchLeo.py</p>
</section>
<section id="how-can-i-use-setuptools-instead-of-bat-files">
<h3><a class="toc-backref" href="#id95">How can I use setuptools instead of .bat files?</a><a class="headerlink" href="#how-can-i-use-setuptools-instead-of-bat-files" title="Permalink to this heading">¶</a></h3>
<p>File under things-I-didn’t-know-but-should-have:</p>
<p>Instead of creating batch files all over the place to fire up python programs, and then having to cope with annoying “Terminate batch job (Y/N)?” with Ctrl-C/Break you can ask python setuptools to create an .exe in the PythonScripts folder.</p>
<p>in same folder as foo.py create setup.py, populate like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="kn">import</span> <span class="n">setup</span>

<span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s1">&#39;Foo for you&#39;</span><span class="p">,</span>
    <span class="n">version</span><span class="o">=</span><span class="s1">&#39;0.3&#39;</span><span class="p">,</span>
    <span class="n">py_modules</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">],</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="s1">&#39;&#39;&#39;</span>
<span class="s1">        [console_scripts]</span>
<span class="s1">        foo = foo</span>
<span class="s1">        &#39;&#39;&#39;</span>
    <span class="p">)</span>
</pre></div>
</div>
<p>Then run “pip –editable install . ” in the same folder. Foo.exe will be created in C:pythonxxScripts. As long as that folder is in path you can use foo like any other command line program. Furthermore the “editable” parameter means we can continue to edit and change foo.py and the changes are always live.</p>
<p>Yeah! No more “pushd ..pathtodatafolder &amp;&amp; python ..pathtocodefoo.py
–do-stuff-here …” for me. :)</p>
</section>
<section id="how-can-scripts-call-functions-from-leo-s-core">
<h3><a class="toc-backref" href="#id96">How can scripts call functions from Leo’s core?</a><a class="headerlink" href="#how-can-scripts-call-functions-from-leo-s-core" title="Permalink to this heading">¶</a></h3>
<p>Leo executes scripts with c and g predefined.</p>
<p>g is the leo.core.leoGlobal. Use g to access any function or class in leo/core/leoGlobals.py:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">g</span><span class="o">.</span><span class="n">app</span>                   <span class="n">A</span> <span class="n">LeoApp</span> <span class="n">instance</span><span class="o">.</span>
<span class="n">g</span><span class="o">.</span><span class="n">app</span><span class="o">.</span><span class="n">gui</span>               <span class="n">A</span> <span class="n">LeoGui</span> <span class="n">instance</span><span class="o">.</span>
<span class="n">g</span><span class="o">.</span><span class="n">app</span><span class="o">.</span><span class="n">pluginsController</span> <span class="n">A</span> <span class="n">LeoPluginsController</span> <span class="n">instance</span><span class="o">.</span>
<span class="n">g</span><span class="o">.</span><span class="n">app</span><span class="o">.*</span>                 <span class="n">Leo</span><span class="s1">&#39;s global variables.</span>
</pre></div>
</div>
<p>c is the Commander object for the present outline. Commander objects define <strong>subcommanders</strong> corresponding to files in leo/core and leo/commands:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># in leo/core...</span>
<span class="n">c</span><span class="o">.</span><span class="n">atFileCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">chapterController</span>
<span class="n">c</span><span class="o">.</span><span class="n">fileCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">findCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">importCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">keyHandler</span> <span class="o">=</span> <span class="n">c</span><span class="o">.</span><span class="n">k</span>
<span class="n">c</span><span class="o">.</span><span class="n">persistenceController</span>
<span class="n">c</span><span class="o">.</span><span class="n">printingController</span>
<span class="n">c</span><span class="o">.</span><span class="n">rstCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">shadowController</span>
<span class="n">c</span><span class="o">.</span><span class="n">tangleCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">testManager</span>
<span class="n">c</span><span class="o">.</span><span class="n">vimCommands</span>

<span class="c1"># In leo/commands...</span>
<span class="n">c</span><span class="o">.</span><span class="n">abbrevCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">controlCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">convertCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">debugCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">editCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">editFileCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">gotoCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">helpCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">keyHandlerCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">killBufferCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">rectangleCommands</span>
<span class="n">c</span><span class="o">.</span><span class="n">spellCommands</span>
</pre></div>
</div>
<p>Scripts can gain access to all of the code in these files via these subcommanders. For example, c.k is an instance of the LeoKeys class in leo/core/leoKeys.py.</p>
</section>
<section id="how-do-i-choose-between-others-and-section-references">
<h3><a class="toc-backref" href="#id97">How do I choose between &#64;others and section references?</a><a class="headerlink" href="#how-do-i-choose-between-others-and-section-references" title="Permalink to this heading">¶</a></h3>
<p>Use &#64;others unless the contents of a node must appear in a certain spot, or in a certain order. For examples, most of Leo’s source files start like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@first</span> <span class="c1"># -*- coding: utf-8 -*-</span>
<span class="o">&lt;&lt;</span> <span class="n">imports</span> <span class="o">&gt;&gt;</span>
<span class="nd">@others</span>
</pre></div>
</div>
<p>The &lt;&lt; imports &gt;&gt; section reference ensures that imports appear first. Another example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@first</span> <span class="c1"># -*- coding: utf-8 -*-</span>
<span class="o">&lt;&lt;</span> <span class="n">imports</span> <span class="o">&gt;&gt;</span>
<span class="o">&lt;&lt;</span> <span class="n">base</span> <span class="n">classes</span> <span class="o">&gt;&gt;</span>
<span class="nd">@others</span>
</pre></div>
</div>
<p>This ensures that base classes are defined before their subclasses.</p>
</section>
<section id="how-to-use-leo-to-make-mathematical-notes">
<h3><a class="toc-backref" href="#id98">How to use leo to make mathematical notes?</a><a class="headerlink" href="#how-to-use-leo-to-make-mathematical-notes" title="Permalink to this heading">¶</a></h3>
<p>If I want to use leo to make mathematical notes, how can I type in some special mathematical symbols? Or is there a good way to make mathematical notes using leo?</p>
<p>===== Terry</p>
<p>I use itex2MML with reStructuredText.  So within Leo you’re looking at LaTeX math markup, and you get outputs in PDF and XHTML, with MathML in the latter.</p>
<p>===== Jose</p>
<p>I’ve been doing this for about a year now.  I use the math docutils directive.  A custom .XCompose file (for example: <a class="reference external" href="https://github.com/kragen/xcompose">https://github.com/kragen/xcompose</a>)  also helps.</p>
<p>===== Terry</p>
<p>I think math was added to docutils after I started using itex2mml, neater to use docutils built in math now I think.</p>
<p>Although having said that, playing with docutils math a bit suggests itex2mml gives more complete support for both MathML and perhaps LaTeX math (with the PDF target).</p>
<p>===== Jose</p>
<p>Terry, your setup is probably more flexible, but I haven’t had any problems with docutils math. It seems to support all the syntax that I’ve found necessary.</p>
<p>I forgot to mention that the viewrendered plug-in doesn’t display math correctly.  I’m not sure what the problem is, I remember trying to figure it out a while back, but I never got anywhere.  It’s not really a big problem though, I have scripts to compile nodes to html/pdfs and open them in firefox/pdf reader; math works fine that way.</p>
<p>===== Offray</p>
<p>Is not properly Leo, but is python related, tailored for math and with a web interface and has leo bindings, check IPython: <a class="reference external" href="http://ipython.org/">http://ipython.org/</a></p>
<p>I’m using it for all my math related writing and I think that point the future of interactive writing in Python. I dream of a body pane on leo with the features of the python qt console.</p>
</section>
<section id="what-is-an-easy-way-to-profile-code">
<h3><a class="toc-backref" href="#id99">What is an easy way to profile code?</a><a class="headerlink" href="#what-is-an-easy-way-to-profile-code" title="Permalink to this heading">¶</a></h3>
<p>I had a need to figure out why a part of some python code I had written was taking too long. I pulled the code into Leo and the relevant part of the outline looked something like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">+</span> <span class="n">Main</span> <span class="n">module</span>
<span class="o">--</span> <span class="n">Generate</span> <span class="n">cryptographic</span> <span class="n">key</span>
<span class="o">--</span> <span class="n">Hashing</span> <span class="n">algorithm</span>
</pre></div>
</div>
<p>etc. So I cloned just the segment I wanted to profile and pulled it under a new section:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">+</span> <span class="n">Main</span> <span class="n">module</span>
<span class="o">--</span> <span class="p">[</span><span class="n">clone</span><span class="p">]</span> <span class="n">Generate</span> <span class="n">cryptographic</span> <span class="n">key</span>
<span class="o">--</span> <span class="n">Hashing</span> <span class="n">algorithm</span>

<span class="o">+</span> <span class="n">Profiling</span> <span class="n">Experiment</span>
<span class="o">--</span> <span class="p">[</span><span class="n">clone</span><span class="p">]</span> <span class="n">Generate</span> <span class="n">cryptographic</span> <span class="n">key</span>
</pre></div>
</div>
<p>And in the body of the “Profiling experiment”, I used this code:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">code_under_here</span> <span class="o">=</span> <span class="s2">&quot;&quot;&quot;</span>
<span class="s2">@others</span>
<span class="s2">&quot;&quot;&quot;</span>

<span class="kn">from</span> <span class="nn">timeit</span> <span class="kn">import</span> <span class="n">Timer</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">Timer</span><span class="p">(</span><span class="s2">&quot;print my_key_generator()&quot;</span><span class="p">,</span> <span class="n">code_under_here</span><span class="p">)</span>
<span class="nb">print</span> <span class="n">t</span><span class="o">.</span><span class="n">timeit</span><span class="p">(</span><span class="n">number</span> <span class="o">=</span> <span class="mi">10</span><span class="p">)</span>
</pre></div>
</div>
<p>And then I hit Control-B to execute the Profiling Experiment body. This let me make adjustments to the code in the clone body and keep hitting Control-B to execute the code with the timeit module to see immediately if what I had done was making a difference.</p>
<p>The great thing about this was that I just used the Leo &#64;others construct to create a wrapper around the code and did not need to litter my code with debug or profiling statements.—Kayvan</p>
</section>
</section>
<section id="trouble-shooting">
<h2><a class="toc-backref" href="#id100">Trouble shooting</a><a class="headerlink" href="#trouble-shooting" title="Permalink to this heading">¶</a></h2>
<section id="error-messages-from-the-rst3-plugin-aren-t-helpful-what-can-i-do">
<h3><a class="toc-backref" href="#id101">Error messages from the rst3 plugin aren’t helpful. What can I do?</a><a class="headerlink" href="#error-messages-from-the-rst3-plugin-aren-t-helpful-what-can-i-do" title="Permalink to this heading">¶</a></h3>
<p>For the most part, <a class="reference external" href="http://docutils.sourceforge.net/">docutils</a> does a good job of reporting errors. <a class="reference external" href="http://docutils.sourceforge.net/">docutils</a> prints a message to the console and inserts an unmistakable error message in the generated .html file. <strong>Important</strong>: On Windows it is helpful to <a class="reference external" href="running.html#running-leo-from-a-console-window">run Leo in a console</a>.</p>
<p>However, in some cases, <a class="reference external" href="http://docutils.sourceforge.net/">docutils</a> crashes instead of properly reporting the problem. There are several workarounds:</p>
<ol class="arabic">
<li><p>The crashes I have seen arise from the following bug in docutils. <strong>Hyperlinks in image:: markup must be lower case</strong>.  This will work:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="o">..</span> <span class="o">|</span><span class="n">back</span><span class="o">|</span> <span class="n">image</span><span class="p">::</span> <span class="n">arrow_lt</span><span class="o">.</span><span class="n">gif</span>
    <span class="p">:</span><span class="n">target</span><span class="p">:</span> <span class="n">faq_</span>
</pre></div>
</div>
<p>This will <strong>crash</strong>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="o">..</span> <span class="o">|</span><span class="n">back</span><span class="o">|</span> <span class="n">image</span><span class="p">::</span> <span class="n">arrow_lt</span><span class="o">.</span><span class="n">gif</span>
    <span class="p">:</span><span class="n">target</span><span class="p">:</span> <span class="n">FAQ_</span>
</pre></div>
</div>
<p>So avoid this crash by making sure to use lower case targets in ‘:target:’ markup.</p>
</li>
<li><p>You can change the <a class="reference external" href="http://docutils.sourceforge.net/">docutils</a> source slightly so that it prints a traceback when it crashes. (The rst3 plugin should be able to do this, but I haven’t figured out how yet.) It’s easy enough to do this:</p></li>
</ol>
<ul>
<li><p>Find the file core.py in top-level docutils folder. Typically this folder will be in Python’s site-packages folder.</p></li>
<li><p>Open core.py in some editor other than Leo.</p></li>
<li><p>Find the method called report_Exceptions.</p></li>
<li><p>Insert the following lines at the very start of this method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span> <span class="s1">&#39;EKR: added traceback&#39;</span>
<span class="kn">import</span> <span class="nn">traceback</span> <span class="p">;</span> <span class="n">traceback</span><span class="o">.</span><span class="n">print_exc</span><span class="p">()</span>
</pre></div>
</div>
</li>
</ul>
<p>This will cause a traceback whenever <a class="reference external" href="http://docutils.sourceforge.net/">docutils</a> crashes. I have found that such tracebacks are generally enough to locate the general area of the problem. <strong>Note</strong>: These tracebacks go to the console window, so you should <a class="reference external" href="running.html#running-leo-from-a-console-window">run Leo in a console</a>.</p>
<ol class="arabic simple" start="3">
<li><p>As a last resort, you can isolate syntax errors by reducing your input files until they work again, then adding sections until you get a crash. This is easy enough to do (when using the rst3 plugin) by change a headline ‘x’ to &#64;rst-ignore-tree x.</p></li>
</ol>
</section>
<section id="how-can-i-move-leo-s-window-back-on-screen">
<h3><a class="toc-backref" href="#id102">How can I move Leo’s window back on screen?</a><a class="headerlink" href="#how-can-i-move-leo-s-window-back-on-screen" title="Permalink to this heading">¶</a></h3>
<p>Leo is starting on one of the external monitors and I have no way to
move it back to my laptop screen.</p>
<p>This has happened to me on Windows for as long as I can remember, mid
1990s and Windows 3. It’s rare, but I don’t think a year has gone by
where it hasn’t occurred to me. At any rate, the most reliable and
portable solution I’ve come across is:</p>
<ul class="simple">
<li><p>Press [Alt]-[Tab] until the invisible program has focus.</p></li>
<li><p>Press [Alt]-[spacebar] to bring up window controls (Move, Size, Min, Max, Close).</p></li>
<li><p>Press [M] to activate Move.
A dotted or thin gray outline of window shape should appear.</p></li>
<li><p>Press arrow cursor keys to move the outline centrally on active screen.
(usually right- and down-arrow)</p></li>
<li><p>Press [enter] when it’s moved on-screen enough to nab the Title bar with the mouse cursor.</p></li>
</ul>
</section>
<section id="how-can-i-run-leo-from-a-console-window">
<h3><a class="toc-backref" href="#id103">How can I run Leo from a console window?</a><a class="headerlink" href="#how-can-i-run-leo-from-a-console-window" title="Permalink to this heading">¶</a></h3>
<p>Leo (and other programs) often send more detailed error messages to stderr, the output stream that goes to the console window. In Linux and MacOS environments, python programs normally execute with the console window visible. On Windows, can run Leo with the console window visible by associating .leo files with python.exe <em>not</em> pythonw.exe.</p>
</section>
<section id="how-can-i-use-python-s-pdb-debugger-with-leo">
<h3><a class="toc-backref" href="#id104">How can I use Python’s pdb debugger with Leo?</a><a class="headerlink" href="#how-can-i-use-python-s-pdb-debugger-with-leo" title="Permalink to this heading">¶</a></h3>
<p>Just <a class="reference external" href="running.html#running-leo-from-a-console-window">run Leo in a console</a>. At the point you want to drop into the debugger, execute this line:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">g</span><span class="o">.</span><span class="n">pdb</span><span class="p">()</span>
</pre></div>
</div>
<p>All output from pdb goes to stdout, which is the console window. It would be good to create a subclass of pdb.Pdb that uses Leo’s log pane rather than a console window, but I haven’t done that. It could be done easily enough in a plugin…</p>
<p><strong>Important</strong>: I recommend using g.trace instead of pdb.  For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">g</span><span class="o">.</span><span class="n">trace</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
</pre></div>
</div>
<p>prints the name of the function or method containing the trace, and the value of
x. g.callers is often useful in combination with g.trace. g.callers(5)
returns the last 5 entries of the call stack. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">g</span><span class="o">.</span><span class="n">trace</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="n">g</span><span class="o">.</span><span class="n">callers</span><span class="p">(</span><span class="mi">5</span><span class="p">))</span>
</pre></div>
</div>
<p>Used this way, g.trace shows you patterns that will be invisible using pdb.</p>
</section>
<section id="how-do-i-get-help">
<h3><a class="toc-backref" href="#id105">How do I get help?</a><a class="headerlink" href="#how-do-i-get-help" title="Permalink to this heading">¶</a></h3>
<p>All questions are welcome at <a class="reference external" href="http://groups.google.com/group/leo-editor">http://groups.google.com/group/leo-editor</a></p>
</section>
<section id="how-do-i-make-ctrl-shift-0-work-on-windows-8-or-10">
<h3><a class="toc-backref" href="#id106">How do I make Ctrl-Shift-0 work on Windows 8 or 10?</a><a class="headerlink" href="#how-do-i-make-ctrl-shift-0-work-on-windows-8-or-10" title="Permalink to this heading">¶</a></h3>
<p>This key is normally bound to delete-comments. It is annoying not to have it work.</p>
<p>The only sure workaround is make other key bindings for add-comments and delete-comments.  I suggest Ctrl-[ and Ctrl-].</p>
<p>At one time I thought the following might work, but it appears that it doesn’t:</p>
<ol class="arabic simple">
<li><p>In the control panel, click Language.
This brings up the “Language” panel.</p></li>
<li><p>Choose “Advanced Settings” in the left area.
This brings up the “Advanced Settings” panel.</p></li>
<li><p>Choose “Change language bar hot keys” in the left area.
This brings up the “Text Services &amp; Input Language” panel.</p></li>
<li><dl class="simple">
<dt>You will see Shift-Ctrl-0 as the binding for “Between input languages”.</dt><dd><p>Select that item and click the “Change Key Sequence” button.
This brings up the “Change Key Sequence” panel.</p>
</dd>
</dl>
</li>
<li><p>Set both radio buttons to “Not Assigned” and click OK.</p></li>
</ol>
</section>
<section id="how-do-i-report-bugs">
<h3><a class="toc-backref" href="#id107">How do I report bugs?</a><a class="headerlink" href="#how-do-i-report-bugs" title="Permalink to this heading">¶</a></h3>
<p>Please consider <em>asking for help</em> at <a class="reference external" href="http://groups.google.com/group/leo-editor">http://groups.google.com/group/leo-editor</a> before filing bug reports.</p>
<p>Please report bugs at <a class="reference external" href="http://bugs.launchpad.net/leo-editor">http://bugs.launchpad.net/leo-editor</a></p>
<p>When reporting a bug, please include <em>all</em> of the following:</p>
<ul class="simple">
<li><p>The version of Leo used.</p></li>
<li><p>The version of Python used.</p></li>
<li><p>The platform or platforms used: Linux, Windows, MacOS.</p></li>
<li><p>A clear description of the problem.</p></li>
<li><p>Information sufficient to recreate the problem.</p></li>
</ul>
<p>It’s polite to make the bug report self contained, so that six weeks later somebody will be able to understand the report as it stands.</p>
</section>
<section id="i-am-having-trouble-installing-leo-on-macos-what-should-i-do">
<h3><a class="toc-backref" href="#id108">I am having trouble installing Leo on MacOS. What should I do?</a><a class="headerlink" href="#i-am-having-trouble-installing-leo-on-macos-what-should-i-do" title="Permalink to this heading">¶</a></h3>
<p>Installing PyQt on MacOS using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">brew</span> <span class="n">install</span> <span class="n">qt</span> <span class="n">sip</span> <span class="n">pyqt</span>
</pre></div>
</div>
<p>may not always work.  In that case, you will see something like this when running Leo:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span>
<span class="n">File</span> <span class="s2">&quot;launchLeo.py&quot;</span><span class="p">,</span> <span class="n">line</span> <span class="mi">8</span><span class="p">,</span> <span class="ow">in</span>
<span class="n">leo</span><span class="o">.</span><span class="n">core</span><span class="o">.</span><span class="n">runLeo</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
<span class="p">[</span><span class="n">Snip</span><span class="p">]</span>
<span class="n">File</span> <span class="s2">&quot;/Users/your-name/git/leo-editor/leo/plugins/qt_text.py&quot;</span><span class="p">,</span>
<span class="n">line</span> <span class="mi">434</span><span class="p">,</span> <span class="ow">in</span> <span class="k">class</span> <span class="nc">LeoLineTextWidget</span><span class="p">(</span><span class="n">QtWidgets</span><span class="o">.</span><span class="n">QFrame</span><span class="p">):</span>
<span class="ne">AttributeError</span><span class="p">:</span> <span class="s1">&#39;NoneType&#39;</span> <span class="nb">object</span> <span class="n">has</span> <span class="n">no</span> <span class="n">attribute</span> <span class="s1">&#39;QFrame&#39;</span>
</pre></div>
</div>
<p>You can verify that PyQt has not been installed by setting the trace switch to True in leoQt.py. This will trace the import commands related to Qt and tell you exactly what is happening.</p>
<p>One Leo user gives this advice:</p>
<p>For anyone with similar problem the homebrew instruction for adding PyQT to the import path are wrong. Instead edit ~/.bash_profile and add this line:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">export</span> <span class="n">PATH</span><span class="o">=</span><span class="s2">&quot;/usr/local/lib/python2.7/site-packages:$</span><span class="si">{PATH}</span><span class="s2">&quot;</span>
</pre></div>
</div>
<p>After this leo editor will open with using the default python installation provided by MacOS.</p>
</section>
<section id="i-can-t-run-the-leobridge-module-outside-of-leo-core-what-should-i-do">
<h3><a class="toc-backref" href="#id109">I can’t run the LeoBridge module outside of leo/core.  What should I do?</a><a class="headerlink" href="#i-can-t-run-the-leobridge-module-outside-of-leo-core-what-should-i-do" title="Permalink to this heading">¶</a></h3>
<p>Question and answer from plumloco.</p>
<p>Add the equivalent of:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sys</span>
<span class="n">leocore</span> <span class="o">=</span> <span class="s2">&quot;path/to/leo/core&quot;</span>
<span class="k">if</span> <span class="n">leocore</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="p">:</span> <span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">leocore</span><span class="p">)</span>
<span class="kn">import</span> <span class="nn">leo.core.leoBridge</span> <span class="k">as</span> <span class="nn">leoBridge</span>
</pre></div>
</div>
<p>at the head of each file that uses leoBridge.</p>
<p>The problem is not importing leoBridge itself but (if I use ‘from leo.core’) the importing of plugins, who get a different leoGlobals from leoBridge, without g.app etc, and so do not work if they rely on dynamic values in g.etc.</p>
<p>&gt; Why can’t you simply add leo/core to sys.path in sitecustomize.py?</p>
<p>Putting leo/core on the python path as you suggest would put forty python modules in the global module namespace for all python programs when I want just one. Also, I have a safe working copy of leo and a cvs/testing version. I would wish to test any programs against the testing version while using the working version, but both /core directories can’t be exposed at the same time.</p>
<p>&gt; Do you need plugins while running from the leoBridge?</p>
<p>Afraid so, at least the rst3 plugin. The solution I am using now is to place:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sys</span><span class="o">.</span><span class="n">modules</span><span class="p">[</span><span class="s1">&#39;leoGlobals&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">leoGlobals</span>
</pre></div>
</div>
<p>in leoBridge after import leo.core.leoGlobals as leoGlobals</p>
<p>This allows my scripts to be portable over the several computers/platforms I need to use them on, and makes testing scripts against multiple leo versions easy. It does mean that my scripts are not portable to other leo users but that is not likely to be a problem.</p>
</section>
<section id="i-can-t-write-imported-files-what-s-going-on">
<h3><a class="toc-backref" href="#id110">I can’t write Imported files.  What’s going on?</a><a class="headerlink" href="#i-can-t-write-imported-files-what-s-going-on" title="Permalink to this heading">¶</a></h3>
<p>The import commands insert &#64;ignore <a class="reference external" href="glossary.html#directives">directives</a> in the top-level <a class="reference external" href="glossary.html#node">node</a>. Leo does this so that you won’t accidentally overwrite your files after importing them. Change the filename following &#64;file (or &#64;file) as desired, then remove the &#64;ignore <a class="reference external" href="glossary.html#directive">directive</a>. Saving the outline will then create the external file.</p>
</section>
<section id="my-old-leo-files-won-t-load-using-leo-4-5-or-later-what-should-i-do">
<h3><a class="toc-backref" href="#id111">My old .leo files won’t load using Leo 4.5 or later. What should I do?</a><a class="headerlink" href="#my-old-leo-files-won-t-load-using-leo-4-5-or-later-what-should-i-do" title="Permalink to this heading">¶</a></h3>
<p>In version 4.5, Leo changed to using a sax parser for .leo files. This can cause problems if your .leo file contains invalid characters. Bugs in previous versions of Leo permitted these bad characters to appear.</p>
<p>The sax parser complains that these characters are not valid in .xml files. Remove these invalid characters as follows:</p>
<ol class="arabic">
<li><p><a class="reference external" href="running.html#running-leo-from-a-console-window">run Leo in a console</a>, and load the .leo file. Near the bottom of the error message you will see a line like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SAXParseException</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">unknown</span><span class="o">&gt;</span><span class="p">:</span><span class="mi">123</span><span class="p">:</span><span class="mi">25</span><span class="p">:</span> <span class="ow">not</span> <span class="n">well</span><span class="o">-</span><span class="n">formed</span> <span class="p">(</span><span class="n">invalid</span> <span class="n">token</span><span class="p">)</span>
</pre></div>
</div>
</li>
</ol>
<p>This line reports a bad character at character 25 of line 123.</p>
<ol class="arabic simple" start="2">
<li><p>Open the .leo file in an external editor. The Scite editor, <a class="reference external" href="http://www.scintilla.org/SciTE.html">http://www.scintilla.org/SciTE.html</a>, is a good choice because it clearly shows non-printing characters. Remove the invalid character, save the .leo file.</p></li>
</ol>
<p>Repeat steps 1 and 2 until all invalid characters are gone.</p>
</section>
<section id="nothing-or-almost-nothing-happens-when-i-start-leo-what-should-i-do">
<h3><a class="toc-backref" href="#id112">Nothing (or almost nothing) happens when I start Leo.  What should I do?</a><a class="headerlink" href="#nothing-or-almost-nothing-happens-when-i-start-leo-what-should-i-do" title="Permalink to this heading">¶</a></h3>
<p>Missing modules can cause installation problems. If the installer doesn’t work (or puts up a dialog containing no text), you may install Leo from the .zip file as described at <a class="reference external" href="installing.html#installing-leo-on-windows">How to install Leo on Windows</a>. However you are installing Leo, be sure to <a class="reference external" href="running.html#running-leo-from-a-console-window">run Leo in a console</a>. because as a last resort Leo prints error messages to the console.</p>
</section>
<section id="running-python-setup-py-install-from-the-leo-directory-doesn-t-work-why-not">
<h3><a class="toc-backref" href="#id113">Running Python setup.py install from the leo directory doesn’t work.  Why not?</a><a class="headerlink" href="#running-python-setup-py-install-from-the-leo-directory-doesn-t-work-why-not" title="Permalink to this heading">¶</a></h3>
<p>Leo’s setup.py script is intended only to create source distributions. It can’t be used to install Leo because Leo is not a Python package.</p>
</section>
<section id="the-new-python-decorator-syntax-causes-problems-what-can-i-do">
<h3><a class="toc-backref" href="#id114">The new Python decorator syntax causes problems.  What can I do?</a><a class="headerlink" href="#the-new-python-decorator-syntax-causes-problems-what-can-i-do" title="Permalink to this heading">¶</a></h3>
<p>This syntax file hack works well enough to work with Leo ‘&#64;’ markup:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">syn</span> <span class="n">region</span> <span class="n">leoComment</span> <span class="n">start</span><span class="o">=</span><span class="s2">&quot;^@</span><span class="se">\\</span><span class="s2">s*&quot;</span> <span class="n">end</span><span class="o">=</span><span class="s2">&quot;^@c</span><span class="se">\\</span><span class="s2">s*$&quot;</span>
<span class="n">syn</span> <span class="n">match</span>   <span class="n">pythonDecorator</span> <span class="s2">&quot;@</span><span class="se">\\</span><span class="s2">S</span><span class="se">\\</span><span class="s2">S+&quot;</span> <span class="n">display</span> <span class="n">nextgroup</span><span class="o">=</span><span class="n">pythonFunction</span> <span class="n">skipwhite</span>
</pre></div>
</div>
</section>
<section id="themes-aren-t-working-for-me-what-should-i-do">
<h3><a class="toc-backref" href="#id115">Themes aren’t working for me. What should I do?</a><a class="headerlink" href="#themes-aren-t-working-for-me-what-should-i-do" title="Permalink to this heading">¶</a></h3>
<ol class="arabic simple">
<li><p>The directory leo-editor/leo/themes contains various theme files. You can load these files from the <a class="reference external" href="File:Open">File:Open</a> Outline menu.</p></li>
</ol>
<p>Opening a theme outline automatically loads the theme. Keep opening outlines until you find one you like.</p>
<ol class="arabic simple" start="2">
<li><p>Close all of the theme files.</p></li>
<li><p>Copy the theme file you chose from leo-editor/leo/themes to ~/.leo/themes (you will have to create the themes folder here) and rename it something like myTheme.leo.  Note that the folder is ~/.leo, not ~.</p></li>
<li><p>Open your myLeoSettings.leo file.</p></li>
</ol>
<p>Add the following to the headline of a new node as a child of your &#64;settings node:
&#64;string theme-name = myTheme.leo</p>
<ol class="arabic simple" start="5">
<li><p>Save the file and restart Leo.</p></li>
</ol>
<p>You should now be using myTheme.leo. You can load myTheme.leo from Leo. The font sizing and colors are under Theme Settings in the tree.</p>
</section>
<section id="why-didn-t-leo-update-my-clean-outline-as-expected">
<h3><a class="toc-backref" href="#id116">Why didn’t Leo update my &#64;clean outline as expected?</a><a class="headerlink" href="#why-didn-t-leo-update-my-clean-outline-as-expected" title="Permalink to this heading">¶</a></h3>
<p>The update algorithm guarantees <em>only</em> that writing an updated &#64;clean outline will generate the updated <strong>public</strong> file.  <strong>Ambiguous lines</strong> could be placed either at the end of one node or the beginning of the following nodes. The update algorithm <em>guesses</em> that such lines should be placed at the end of the previous node.</p>
<p>Happily, guesses are not serious. Once you move an ambiguous node and save the Leo file, the update algorithm will not have to guess where the line belongs the next time Leo reads the &#64;clean files.</p>
</section>
<section id="why-do-qt-windows-disappear-in-my-scripts">
<h3><a class="toc-backref" href="#id117">Why do Qt windows disappear in my scripts?</a><a class="headerlink" href="#why-do-qt-windows-disappear-in-my-scripts" title="Permalink to this heading">¶</a></h3>
<p>&#64;pagewidth 75</p>
<ol class="upperalpha" start="17">
<li><p>When I run the following script I see a window appear and then immediately disappear:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">leo.core.leoQt</span> <span class="kn">import</span> <span class="n">QtWidgets</span><span class="p">,</span> <span class="n">QtCore</span>
<span class="n">w</span> <span class="o">=</span> <span class="n">QtWidgets</span><span class="o">.</span><span class="n">QWidget</span><span class="p">()</span>
<span class="n">w</span><span class="o">.</span><span class="n">resize</span><span class="p">(</span><span class="mi">250</span><span class="p">,</span> <span class="mi">150</span><span class="p">)</span>
<span class="n">w</span><span class="o">.</span><span class="n">move</span><span class="p">(</span><span class="mi">300</span><span class="p">,</span> <span class="mi">300</span><span class="p">)</span>
<span class="n">w</span><span class="o">.</span><span class="n">setWindowTitle</span><span class="p">(</span><span class="s1">&#39;Simple test&#39;</span><span class="p">)</span>
<span class="n">w</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>
</pre></div>
</div>
</li>
</ol>
<p>What’s going on?</p>
<ol class="upperalpha">
<li><p>When the script exits the sole reference to the window, w, ceases to exist, so the window is destroyed (garbage collected). To keep the window open, add the following code as the last line to keep the reference alive:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">g</span><span class="o">.</span><span class="n">app</span><span class="o">.</span><span class="n">scriptsDict</span><span class="p">[</span><span class="s1">&#39;my-script_w&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">w</span>
</pre></div>
</div>
</li>
</ol>
<p>This reference will persist until the next time you run the execute-script. If you want something even more permanent, you can do something like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">g</span><span class="o">.</span><span class="n">app</span><span class="o">.</span><span class="n">my_script_w</span> <span class="o">=</span> <span class="n">w</span>
</pre></div>
</div>
</section>
<section id="why-isn-t-the-spell-tab-showing">
<h3><a class="toc-backref" href="#id118">Why isn’t the Spell tab showing?</a><a class="headerlink" href="#why-isn-t-the-spell-tab-showing" title="Permalink to this heading">¶</a></h3>
<p>Leo will show the Spell tab if:</p>
<ol class="arabic simple">
<li><p>The pyenchant spell checker has been installed or,</p></li>
<li><p>Leo finds a main spelling dictionary at ~/.leo/main_spelling_dict.txt.
In this case, Leo uses a pure-python spell checker.</p></li>
</ol>
<p>So if the Spell tab is not visible do the following:</p>
<ul class="simple">
<li><p>Download main_spelling_dict.zip from
<a class="reference external" href="https://sourceforge.net/projects/leo/files/Miscellaneous/">https://sourceforge.net/projects/leo/files/Miscellaneous/</a></p></li>
<li><p>Unzip this file to ~/.leo/main_spelling_dict.txt.</p></li>
</ul>
<p>The show-spell-info command tells what spell checker is in effect and the location of the main and user spell dictionaries.</p>
</section>
</section>
<section id="id3">
<h2><a class="toc-backref" href="#id119">Unicode</a><a class="headerlink" href="#id3" title="Permalink to this heading">¶</a></h2>
<section id="i-can-not-enter-non-ascii-characters-what-can-i-do">
<h3><a class="toc-backref" href="#id120">I can not enter non-ascii characters.  What can I do?</a><a class="headerlink" href="#i-can-not-enter-non-ascii-characters-what-can-i-do" title="Permalink to this heading">¶</a></h3>
<p>Set &#64;bool ignore_unbound_non_ascii_keys = False in LeoSettings.leo or myLeoSettings.leo.</p>
</section>
<section id="some-characters-in-external-files-look-funny-what-can-i-do">
<h3><a class="toc-backref" href="#id121">Some characters in external files look funny. What can I do?</a><a class="headerlink" href="#some-characters-in-external-files-look-funny-what-can-i-do" title="Permalink to this heading">¶</a></h3>
<p>Internally, Leo represents all strings as unicode. Leo translates from a particular encoding to <a class="reference external" href="http://www.unicode.org/">Unicode</a> when reading .leo files or external files. Leo translates from <a class="reference external" href="http://www.unicode.org/">Unicode</a> to a particular encoding when writing external files. You may see strange looking characters if your text editor is expecting a different encoding. The encoding used in any external file is shown in the <a class="reference external" href="mailto:#&#37;&#52;&#48;+leo">#<span>&#64;</span>+leo</a> sentinel line like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">#@+leo-encoding=iso-8859-1.</span>
</pre></div>
</div>
<p><strong>Exception</strong>: the encoding is UTF-8 if no -encoding= field exists. You can also use the &#64;encoding <a class="reference external" href="glossary.html#directive">directive</a> to set the encoding for individual external files. If no &#64;encoding <a class="reference external" href="glossary.html#directive">directive</a> is in effect, Leo uses the following <a class="reference external" href="glossary.html#settings">settings</a> to translate to and from unicode:</p>
<dl>
<dt>default_derived_file_encoding</dt><dd><p>The encoding used for external files if no &#64;encoding <a class="reference external" href="glossary.html#directive">directive</a> is in effect.
This setting also controls the encoding of files that Leo writes.
The default is UTF-8 (case not important).</p>
</dd>
<dt>new_leo_file_encoding</dt><dd><p>The encoding specified in the following line of new .leo files:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;&gt;
</pre></div>
</div>
<p>The default is UTF-8 (upper case for compatibility for old versions of Leo).</p>
</dd>
</dl>
</section>
<section id="i-get-weird-results-when-defining-unicode-strings-in-scripts-what-is-going-on">
<h3><a class="toc-backref" href="#id122">I get weird results when defining unicode strings in scripts.  What is going on?</a><a class="headerlink" href="#i-get-weird-results-when-defining-unicode-strings-in-scripts-what-is-going-on" title="Permalink to this heading">¶</a></h3>
<p>Add the following as the <em>very first line</em> of your scripts:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@first</span> <span class="c1"># -*- coding: utf-8 -*-</span>
</pre></div>
</div>
<p>Without this line, constructs such as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">u</span> <span class="o">=</span> <span class="sa">u</span><span class="s1">&#39;a-(2 unicode characters here)-z&#39;</span>
<span class="n">u</span> <span class="o">=</span> <span class="s1">&#39;a-(2 unicode characters here)-z&#39;</span>
</pre></div>
</div>
<p>will not work when executed with Leo’s execute script command. Indeed, the Execute Script command creates the script by writing the tree containing the script to a string. This is done using Leo’s write logic, and this logic converts the unicode input to a utf-8 encoded string. So <em>all non-ascii characters</em> get converted to their equivalent in the utf-8 encoding. Call these encoding &lt;e1&gt; and &lt;e2&gt;. In effect the script becomes:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">u</span> <span class="o">=</span> <span class="sa">u</span><span class="s1">&#39;a-&lt;e1&gt;-&lt;e2&gt;-z&#39;</span>
<span class="n">u</span> <span class="o">=</span> <span class="s1">&#39;a-&lt;e2&gt;-&lt;e&gt;-z&#39;</span>
</pre></div>
</div>
<p>which is certainly <em>not</em> what the script writer intended! Rather than defining strings using actual characters, Instead, one should use the equivalent escape sequences. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">u</span> <span class="o">=</span> <span class="sa">u</span><span class="s1">&#39;a-</span><span class="se">\\</span><span class="s1">u0233-</span><span class="se">\\</span><span class="s1">u8ce2-z&#39;</span>
<span class="n">u</span> <span class="o">=</span> <span class="s1">&#39;a-</span><span class="se">\\</span><span class="s1">u0233-</span><span class="se">\\</span><span class="s1">u8ce2-z&#39;</span>
</pre></div>
</div>
</section>
<section id="some-characters-are-garbled-when-importing-files-what-can-i-do">
<h3><a class="toc-backref" href="#id123">Some characters are garbled when importing files. What can I do?</a><a class="headerlink" href="#some-characters-are-garbled-when-importing-files-what-can-i-do" title="Permalink to this heading">¶</a></h3>
<p>The encoding used in the file being imported doesn’t match the encoding in effect for Leo. Use the &#64;encoding <a class="reference external" href="glossary.html#directive">directive</a> in an ancestor of the <a class="reference external" href="glossary.html#node">node</a> selected when doing the Import <a class="reference external" href="commands.html">command</a> to specify the encoding of file to be imported.</p>
</section>
<section id="python-s-print-statement-shows-byte-hash-for-unicode-characters-what-can-i-do">
<h3><a class="toc-backref" href="#id124">Python’s print statement shows ‘byte hash’ for unicode characters.  What can I do?</a><a class="headerlink" href="#python-s-print-statement-shows-byte-hash-for-unicode-characters-what-can-i-do" title="Permalink to this heading">¶</a></h3>
<p>First, you must change Python’s default encoding to something other than ‘ascii’.  To do this, put the following in your sitecustomize.py file in Python’s Lib folder:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sys</span>
<span class="n">sys</span><span class="o">.</span><span class="n">setdefaultencoding</span><span class="p">(</span><span class="s1">&#39;utf-8&#39;</span><span class="p">)</span> <span class="c1"># &#39;iso-8859-1&#39; is another choice.</span>
</pre></div>
</div>
<p>You must restart Python after doing this: sys.setdefaultencoding can not be called after Python starts up.</p>
<p>Leo’s g.es_print and g.pr functions attempts to convert incoming arguments to unicode using the default encoding. For example, the following Leo script shows various ways of printing La Peña properly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@first</span> <span class="c1"># -*- coding: utf-8 -*-</span>

<span class="kn">import</span> <span class="nn">sys</span>
<span class="n">e</span> <span class="o">=</span> <span class="n">sys</span><span class="o">.</span><span class="n">getdefaultencoding</span><span class="p">()</span>
<span class="nb">print</span> <span class="s1">&#39;encoding&#39;</span><span class="p">,</span><span class="n">e</span>
<span class="n">table</span> <span class="o">=</span> <span class="p">(</span>
    <span class="s1">&#39;La Peña&#39;</span><span class="p">,</span>
    <span class="n">unicode</span><span class="p">(</span><span class="s1">&#39;La Peña&#39;</span><span class="p">,</span><span class="s1">&#39;utf-8&#39;</span><span class="p">),</span>
    <span class="sa">u</span><span class="s1">&#39;La Peña&#39;</span><span class="p">,</span>
    <span class="sa">u</span><span class="s1">&#39;La Pe</span><span class="se">\\</span><span class="s1">xf1a&#39;</span><span class="p">,</span>
<span class="p">)</span>

<span class="k">for</span> <span class="n">s</span> <span class="ow">in</span> <span class="n">table</span><span class="p">:</span>
    <span class="nb">print</span> <span class="nb">type</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
    <span class="n">g</span><span class="o">.</span><span class="n">es_print</span><span class="p">(</span><span class="s1">&#39;g.es_print&#39;</span><span class="p">,</span><span class="n">s</span><span class="p">)</span>
    <span class="k">if</span> <span class="nb">type</span><span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">type</span><span class="p">(</span><span class="sa">u</span><span class="s1">&#39;a&#39;</span><span class="p">):</span>
        <span class="n">s</span> <span class="o">=</span> <span class="n">unicode</span><span class="p">(</span><span class="n">s</span><span class="p">,</span><span class="n">e</span><span class="p">)</span>
    <span class="nb">print</span> <span class="s1">&#39;print     &#39;</span><span class="p">,</span><span class="n">s</span>
    <span class="nb">print</span> <span class="s1">&#39;repr(s)   &#39;</span><span class="p">,</span><span class="nb">repr</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
</pre></div>
</div>
<p>For still more details, see: <a class="reference external" href="http://www.diveintopython.org/xml_processing/unicode.html">http://www.diveintopython.org/xml_processing/unicode.html</a></p>
</section>
</section>
<section id="vim">
<h2><a class="toc-backref" href="#id125">Vim</a><a class="headerlink" href="#vim" title="Permalink to this heading">¶</a></h2>
<section id="how-can-i-use-leo-s-bridge-in-vim">
<h3><a class="toc-backref" href="#id126">How can I use Leo’s bridge in vim?</a><a class="headerlink" href="#how-can-i-use-leo-s-bridge-in-vim" title="Permalink to this heading">¶</a></h3>
<p>This script appends the outline headlines, indented, to the current vim buffer:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">leo.core.leoBridge</span> <span class="k">as</span> <span class="nn">leoBridge</span>
<span class="kn">import</span> <span class="nn">vim</span>

<span class="n">controller</span> <span class="o">=</span> <span class="n">leoBridge</span><span class="o">.</span><span class="n">controller</span><span class="p">(</span>
    <span class="n">gui</span><span class="o">=</span><span class="s1">&#39;nullGui&#39;</span><span class="p">,</span>
    <span class="n">loadPlugins</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>  <span class="c1"># True: attempt to load plugins.</span>
    <span class="n">readSettings</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>  <span class="c1"># True: read standard settings files.</span>
    <span class="n">silent</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>  <span class="c1"># True: don&#39;t print signon messages.</span>
    <span class="n">verbose</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>  <span class="c1"># True: print informational messages.</span>
<span class="p">)</span>
<span class="n">g</span> <span class="o">=</span> <span class="n">controller</span><span class="o">.</span><span class="n">globals</span><span class="p">()</span>
<span class="n">c</span> <span class="o">=</span> <span class="n">controller</span><span class="o">.</span><span class="n">openLeoFile</span><span class="p">(</span><span class="s2">&quot;/home/tbrown/.leo/del.leo&quot;</span><span class="p">)</span>

<span class="k">def</span> <span class="nf">dent</span><span class="p">(</span><span class="n">node</span><span class="p">,</span> <span class="n">result</span><span class="p">,</span> <span class="n">level</span><span class="o">=</span><span class="mi">0</span><span class="p">):</span>
    <span class="n">result</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;  &#39;</span> <span class="o">*</span> <span class="n">level</span> <span class="o">+</span> <span class="n">node</span><span class="o">.</span><span class="n">h</span><span class="p">)</span>
    <span class="k">for</span> <span class="n">child</span> <span class="ow">in</span> <span class="n">node</span><span class="o">.</span><span class="n">children</span><span class="p">:</span>
        <span class="n">dent</span><span class="p">(</span><span class="n">child</span><span class="p">,</span> <span class="n">result</span><span class="p">,</span> <span class="n">level</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">result</span>

<span class="n">result</span> <span class="o">=</span> <span class="p">[]</span>
<span class="n">dent</span><span class="p">(</span><span class="n">c</span><span class="o">.</span><span class="n">hiddenRootNode</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span>
<span class="n">vim</span><span class="o">.</span><span class="n">current</span><span class="o">.</span><span class="n">buffer</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">:]</span> <span class="o">=</span> <span class="n">result</span>
</pre></div>
</div>
<p>It can be invoked with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">:</span><span class="n">py</span> <span class="kn">import</span> <span class="nn">leodent</span>
</pre></div>
</div>
<p>assuming it’s in a file leodent.py and on the Python path.</p>
</section>
</section>
<section id="work-flow">
<h2><a class="toc-backref" href="#id127">Work flow</a><a class="headerlink" href="#work-flow" title="Permalink to this heading">¶</a></h2>
<section id="how-can-i-organize-data-so-i-can-find-stuff-later">
<h3><a class="toc-backref" href="#id128">How can I organize data so I can find stuff later?</a><a class="headerlink" href="#how-can-i-organize-data-so-i-can-find-stuff-later" title="Permalink to this heading">¶</a></h3>
<p>When organizing data into nodes, <strong>every item should clearly belong to exactly one top-level category</strong>. In other words, avoid top-level <em>aggregate</em> categories.</p>
<p>For example, the following are poor top-level categories. They are poor because any item in them could be placed in a more explicit category:</p>
<ul class="simple">
<li><p>Contrib</p></li>
<li><p>Developing Leo</p></li>
<li><p>Important</p></li>
<li><p>Maybe</p></li>
<li><p>Others</p></li>
<li><p>Prototype</p></li>
<li><p>Recent</p></li>
<li><p>Won’t do/Can’t do</p></li>
</ul>
<p>We all have had bad experiences with the dreaded “Others” category. The Aha! is that all aggregate categories are just as bad as “Others”.</p>
<p><strong>Note</strong>: I have been talking only about top-level categories.  Within a single category aggregate categories may be useful.  However, when possible I prefer to mark items rather than create subcategories. For example, <code class="docutils literal notranslate"><span class="pre">*</span></code> now marks all “Important” items in leoToDo.txt and scripts.leo.  This makes it easy to find important items in a particular category.  To find <em>all</em> important items one could do a regex search for <code class="docutils literal notranslate"><span class="pre">^\*</span></code> in headlines.</p>
</section>
<section id="how-can-i-restore-focus-without-using-the-mouse">
<h3><a class="toc-backref" href="#id129">How can I restore focus without using the mouse</a><a class="headerlink" href="#how-can-i-restore-focus-without-using-the-mouse" title="Permalink to this heading">¶</a></h3>
<p>It sometimes happens that the focus gets left in a Leo widget that doesn’t support Leo’s key bindings. You would think that you would have to use the mouse to click in, say, the body pane so that you can use Leo’s key bindings again.</p>
<p>But you don’t have to do that.  Instead, use Alt-tab once to change away from Leo, and then use Alt-tab again to change back to Leo.  When you do this, Leo puts focus in the body pane and you are all set.</p>
</section>
<section id="how-can-i-see-two-nodes-at-once">
<h3><a class="toc-backref" href="#id130">How can I see two nodes at once?</a><a class="headerlink" href="#how-can-i-see-two-nodes-at-once" title="Permalink to this heading">¶</a></h3>
<p>By Rich Ries. I often rework C code that’s already been “Leo-ized”–the first pass was quick and dirty to get it going. When I do subsequent passes, I wind up with subnodes that are out of order with the sequence found in the main <a class="reference external" href="glossary.html#node">node</a>. It’s not a big deal, but I like ‘em ordered. With just one editor pane, clicking on the <a class="reference external" href="glossary.html#node">node</a> to move would switch focus to that <a class="reference external" href="glossary.html#node">node</a>. I’d then need to re-focus on the main <a class="reference external" href="glossary.html#node">node</a>. A minor nuisance, but it does slow you down.</p>
<p>My solution is to open a second editor with its focus on the main <a class="reference external" href="glossary.html#node">node</a>. Switch to the other editor, and, referring to the first editor pane, move the nodes as you like. The second editor’s pane will change focus to the <a class="reference external" href="glossary.html#node">node</a> you’re moving, but the first editor will stay focused on the main <a class="reference external" href="glossary.html#node">node</a>. It’s a lot easier to do than to describe!</p>
</section>
<section id="how-can-i-use-leo-cooperatively-without-sentinels">
<h3><a class="toc-backref" href="#id131">How can I use Leo cooperatively without sentinels?</a><a class="headerlink" href="#how-can-i-use-leo-cooperatively-without-sentinels" title="Permalink to this heading">¶</a></h3>
<p>Most people will find using &#64;clean trees to be most useful. Use &#64;auto-rst, &#64;auto-vimoutline or &#64;auto-org when using rST, vimoutline or Emacs org mode files.</p>
</section>
<section id="how-can-i-use-the-gtd-workflow-in-leo">
<h3><a class="toc-backref" href="#id132">How can I use the GTD workflow in Leo?</a><a class="headerlink" href="#how-can-i-use-the-gtd-workflow-in-leo" title="Permalink to this heading">¶</a></h3>
<p>GTD (Getting Things Done) <a class="reference external" href="http://www.amazon.com/Getting-Things-Done-Stress-Free-Productivity/dp/0142000280">http://www.amazon.com/Getting-Things-Done-Stress-Free-Productivity/dp/0142000280</a> is, by far, the best productivity book I have ever read. Many aspects of Leo are idea for putting GTD into practice.</p>
<p>Here is a surprisingly useful workflow tip related to GTD.</p>
<p>Ideas often “intrude” when I am busy with something else. When that happens, I create a top-level node of the form:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">**</span> <span class="n">description</span> <span class="n">of</span> <span class="n">idea</span>
</pre></div>
</div>
<p>Now I can continue what I was doing! This is such a simple idea, but it’s really really important: it means I never have to put off getting my ideas into Leo. The “**” draws my attention to the new to-do item. Later, when I am not fully immersed in the previous task, I can put the “**” node somewhere else.</p>
<p>It’s super important to deal with new ideas <em>instantly</em> but <em>without</em> greatly interrupting the task at hand. Creating “**” nodes does that. This new workflow has been a big improvement to my GTD practice.</p>
</section>
<section id="what-s-the-recommended-way-to-upgrade-leo">
<h3><a class="toc-backref" href="#id133">What’s the recommended way to upgrade Leo?</a><a class="headerlink" href="#what-s-the-recommended-way-to-upgrade-leo" title="Permalink to this heading">¶</a></h3>
<ol class="arabic simple">
<li><p>Archive and remove the previous version of Leo.</p></li>
<li><p>Download the nightly snapshot zip file.</p></li>
<li><p>Unzip it into the same place as the previous version.</p></li>
<li><p>Enjoy your up-to-date Leo code…</p></li>
</ol>
<p>To make this work, it’s important to keep your folder containing Leo separate from your .mySettings.leo and any data files.</p>
</section>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="leo_toc.html">
              <img class="logo" src="_static/LeoLogo.svg" alt="Logo"/>
            </a></p>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="toc-more-links.html"
                          title="previous chapter">More Leo Links</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="cheatsheet.html"
                          title="next chapter">Leo’s Cheat Sheet</a></p>
  </div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>

      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="cheatsheet.html" title="Leo’s Cheat Sheet"
             >next</a> |</li>
        <li class="right" >
          <a href="toc-more-links.html" title="More Leo Links"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="leo_toc.html">Leo 6.7.2 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="toc-more-links.html" >More Leo Links</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">FAQ</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 1997-2023, Edward K. Ream.
      Last updated on February 28, 2023.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.3.0.
    </div>
  </body>
</html>